Skip to main content
GuidesAPI ReferenceExamples

Customer

|

The Customer Rest API allows you to manage customer records within the Fleet Management system. You can create, retrieve, update, and delete customer data. This Rest API supports filtering, sorting, and pagination to help manage large datasets efficiently.

Customer Object Fields​

FieldTypeDescription
idIntegerUnique identifier for the customer.
locationObjectCoordinates of the customer’s location.
aliasStringShort name or identifier for the customer.
firstNameStringCustomer's first name.
lastNameStringCustomer's last name.
addressObjectDetailed address information of the customer.
emailStringEmail address of the customer.
phoneNumberStringCustomer's contact phone number.
customDataString
Additional customer-specific data.

Endpoints​

1. Create Customer​

Description: Adds a new customer to the database. The id field will be populated, it will return a list of customers with the id field populated

  • Method: POST
  • Endpoint: /customers
  • Headers:
    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad Request
  • The customer does not have the coordinates set.
  • The email set for the customer has wrong format.
  • The phone number set for the customer has wrong format.
401 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.
Note

If the operation is successful, the Customer object will have its id field populated. If the operation fails, an error code is returned, which can be interpreted as described in the Returned error codes section.

Example:​

  • Request Body:
[
  {
    "alias": "Magic Customer",
    "firstName": "Magic",
    "lastName": "Customer",
    "address": {
      "country": "France",
      "state": "Île-de-France",
      "county": "Paris",
      "city": "Paris",
      "postalCode": "75010",
      "streetName": "Rue Gustave Goublier",
      "streetNumber": "2",
      "extra": ""
    },
    "email": "magiccustomer@example.com",
    "phoneNumber": "+1202555018",
    "location": [
      48.870852,
      2.356148
    ],
    "customData": ""
  },
  {
    "alias": "Magic Customer 2",
    "firstName": "Magic",
    "lastName": "Customer 2",
    "address": {
      "country": "",
      "state": "",
      "county": "",
      "city": "",
      "postalCode": "",
      "streetName": "",
      "streetNumber": ""
    },
    "email": "magiccustomer2@example.com",
    "phoneNumber": "+1202555018",
    "location": [
      48.870852,
      2.356148
    ],
    "customData": "communicationPreference: email"
  }
]
  • Response Body: (error code 200)
{
  "customers": [
    {
      "id": 1838721,
      "alias": "Magic Customer",
      "firstName": "Magic",
      "lastName": "Customer",
      "address": {
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "postalCode": "75010",
        "streetName": "Rue Gustave Goublier",
        "streetNumber": "2",
        "extra": ""
      },
      "email": "magiccustomer@example.com",
      "phoneNumber": "+1202555018",
      "location": [
        48.870852,
        2.356148
      ],
      "customData": ""
    },
    {
      "id": 1838722,
      "alias": "Magic Customer2",
      "firstName": "Magic",
      "lastName": "Customer2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "email": "magiccustomer2@example.com",
      "phoneNumber": "+1202555018",
      "location": [
        48.870852,
        2.356148
      ],
      "customData": "communicationPreference: email"
    }
  ]
}

2. Get All Customers​

Description: Fetches a list of all customers with optional filtering.

  • Method: GET
  • Endpoint: /customers
  • Headers:
    • Authorization: YOUR_API_KEY
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers
  • Query Parameters:
    • search (string, optional) – General search term across customers.
    • id (string, optional) – Filter by customer ID (id=value:exact for exact match).
    • alias (string, optional) – Filter by customer alias (alias=value:exact for exact match).
    • firstName (string, optional) – Filter by first name (firstName=value:exact for exact match).
    • lastName (string, optional) – Filter by last name (lastName=value:exact for exact match).
    • location (string, optional) – Filter by location (location=value:exact for exact match).
    • country (string, optional) – Filter by country (country=value:exact for exact match).
    • state (string, optional) – Filter by state (state=value:exact for exact match).
    • county (string, optional) – Filter by county (county=value:exact for exact match).
    • city (string, optional) – Filter by city (city=value:exact for exact match).
    • postalCode (string, optional) – Filter by postal code (postalCode=value:exact for exact match).
    • streetName (string, optional) – Filter by street name (streetName=value:exact for exact match).
    • streetNumber (string, optional) – Filter by street number (streetNumber=value:exact for exact match).
    • extra (string, optional) – Filter by extra address value (extra=value:exact for exact match).
    • email (string, optional) – Filter by email (email=value:exact for exact match).
    • phoneNumber (string, optional) – Filter by phone number (phoneNumber=value:exact for exact match).
    • customData (string, optional) – Filter by custom data (customData=value:exact for exact match).
    • sort (string, optional) – Sorting format: column1:asc/desc,column2:asc/desc
      • Available columns: id, alias, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, email, phoneNumber, customData.
    • includeColumns (string, optional) – Specify which columns to include.
      • Available columns: id, alias, idAddress, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, email, phoneNumber, customData
    • page (integer, optional) – Page number for pagination.
    • per_page (integer, optional) – Number of items per page.
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe values sent for page and per_page parameters are incorrect; should be greater than 0.
401 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Response Body: (error code 200)
{
  "customers": [
    {
      "id": 1838721,
      "alias": "Magic Customer",
      "firstName": "Magic",
      "lastName": "Customer",
      "address": {
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "postalCode": "75010",
        "streetName": "Rue Gustave Goublier",
        "streetNumber": "2",
        "extra": ""
      },
      "email": "magiccustomer@example.com",
      "phoneNumber": "+1202555018",
      "location": [
        48.870852,
        2.356148
      ],
      "customData": ""
    },
    {
      "id": 1838722,
      "alias": "Magic Customer2",
      "firstName": "Magic",
      "lastName": "Customer2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "email": "magiccustomer2@example.com",
      "phoneNumber": "+1202555018",
      "location": [
        48.870852,
        2.356148
      ],
      "customData": "communicationPreference: email"
    }
  ]
}

3. Get a Customer by ID​

Description: Retrieves a specific customer by ID.

  • Method: GET
  • Endpoint: /customers/{id}
  • Headers:
    • Authorization: YOUR_API_KEY
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers/{id}
  • Path Parameter:
    • id (integer, *required) - The unique customer ID.
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCustomer not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Response Body: (error code 200)
{
  "id": 1838721,
  "alias": "Magic Customer",
  "firstName": "Magic",
  "lastName": "Customer",
  "address": {
    "country": "France",
    "state": "Île-de-France",
    "county": "Paris",
    "city": "Paris",
    "postalCode": "75010",
    "streetName": "Rue Gustave Goublier",
    "streetNumber": "2",
    "extra": ""
  },
  "email": "magiccustomer@example.com",
  "phoneNumber": "+1202555018",
  "location": [
    48.870852,
    2.356148
  ],
  "customData": ""
}

4. Update a Customer​

Description: Updates an existing customer record.

  • Method: PUT
  • Endpoint: /customers/{id}
  • Headers:
    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers/{id}
  • Path Parameter:
    • id (integer, *required) - Customer ID.
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad Request
  • The customer does not have the coordinates set.
  • The email set for the customer has wrong format.
  • The phone number set for the customer has wrong format.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCustomer not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Request Body:
{
  "id": 1838721,
  "alias": "Magic Customer",
  "firstName": "Magic",
  "lastName": "Customer",
  "address": {
    "country": "France",
    "state": "Île-de-France",
    "county": "Paris",
    "city": "Paris",
    "postalCode": "75010",
    "streetName": "Rue Gustave Goublier",
    "streetNumber": "2",
    "extra": ""
  },
  "email": "magiccustomer@example.com",
  "phoneNumber": "+1202555018",
  "location": [
    48.870852,
    2.356148
  ],
  "customData": ""
}
  • Response Body: (error code 200)
{
  "message": "Operation done successfully",
}

5. Delete Customers​

Description: Deletes customers from the system.

  • Method: DELETE
  • Endpoint: /customers
  • Headers:
    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCan't delete customers because at least one of them does not exist.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Request Body: -List of customer IDs to delete.
  [12345, 23456, 34567]
  • Response Body: (error code 200)
{
  "message": "Operation done successfully",
}

6. Get Customer History​

Description: Retrieves the order history and associated optimizations for a specific customer.

  • Method: GET
  • Endpoint: /customers/{id}/history
  • Headers:
    • Authorization: YOUR_API_KEY
    • Content-Type: application/json
  • URL: https://fleetmanagement.magiclaneapis.com/v1/customers/{id}/history Path Parameter:
  • id (integer, *required) - The unique customer ID.
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe customer was not found or its history couldn’t be retrieved.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCustomer not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Response Body: (error code 200)
{
  "history": [
    {
      "order": {
        "id": 933799,
        "creationTimestamp": 1744096603223,
        "customerInfo": {
          "id": 1839506,
          "alias": "",
          "firstName": "",
          "lastName": "",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "email": "c1@yahoo.com",
          "phoneNumber": "+12025550181",
          "location": [
            48.827327,
            2.342267
          ],
          "customData": ""
        },
        "location": [
          48.827327,
          2.342267
        ],
        "alias": "",
        "firstName": "",
        "lastName": "",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "phoneNumber": "+12025550181",
        "customData": "",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          420,
          1086
        ],
        "serviceTime": 0,
        "depotId": 0
      },
      "optimizationAndRoute": [
        {
          "optimization": {
            "id": 139950,
            "orders": [
              {
                "id": 933799,
                "creationTimestamp": 1744096603223,
                "customerInfo": {
                  "id": 1839506,
                  "alias": "",
                  "firstName": "",
                  "lastName": "",
                  "address": {
                    "country": "",
                    "state": "",
                    "county": "",
                    "city": "",
                    "postalCode": "",
                    "streetName": "",
                    "streetNumber": ""
                  },
                  "email": "c1@yahoo.com",
                  "phoneNumber": "+12025550181",
                  "location": [
                    48.827327,
                    2.342267
                  ],
                  "customData": ""
                },
                "location": [
                  48.827327,
                  2.342267
                ],
                "alias": "",
                "firstName": "",
                "lastName": "",
                "address": {
                  "country": "",
                  "state": "",
                  "county": "",
                  "city": "",
                  "postalCode": "",
                  "streetName": "",
                  "streetNumber": ""
                },
                "phoneNumber": "+12025550181",
                "customData": "",
                "type": 0,
                "status": 0,
                "state": 1,
                "priority": 0,
                "numberOfPackages": 0,
                "weight": 0,
                "cube": 0,
                "revenue": 0,
                "timeWindow": [
                  420,
                  1086
                ],
                "serviceTime": 0,
                "depotId": 0
              }
            ],
            "departures": [
              {
                "depotId": 0,
                "alias": "Departure1",
                "location": [
                  48.870569,
                  2.356448
                ],
                "address": {
                  "country": "France",
                  "state": "",
                  "county": "Nouvelle-Aquitaine",
                  "city": "Poitiers",
                  "postalCode": "86000",
                  "streetName": "Boulevard Chasseigne",
                  "streetNumber": "34"
                },
                "matchedLocation": [
                  2147483647,
                  2147483647
                ],
                "numberOfPackages": 0,
                "weight": 0,
                "cube": 0,
                "timeToNext": 0,
                "distanceToNext": 0,
                "departureTime": 0
              }
            ],
            "destinations": [],
            "vehicles": [
              {
                "id": 139812,
                "type": 0,
                "status": 0,
                "name": "Car vehicle",
                "manufacturer": "",
                "model": "",
                "fuelType": 2,
                "lastPosition": [
                  2147483647,
                  2147483647
                ],
                "consumption": 6.5,
                "plate": "",
                "maxLoadWeight": 60,
                "maxLoadCube": 50,
                "height": 0,
                "width": 0,
                "weight": 0,
                "length": 0,
                "axleLoad": 0,
                "fixedCost": 0,
                "costPerHour": 420,
                "startTime": 1439,
                "endTime": 1439
              }
            ],
            "vehiclesConstraints": [
              {
                "fuelPrice": 1.0700000524520874,
                "startDate": 1596758400000,
                "maxNumberOfPackages": 53,
                "minNumberOfOrders": 0,
                "maxNumberOfOrders": 99999999,
                "minDistance": 0,
                "maxDistance": 100000000,
                "maxRevenue": 85
              }
            ],
            "configurationParameters": {
              "name": "Paris - test optimization",
              "ignoreTimeWindow": false,
              "allowDroppingOrders": false,
              "groupingOrders": false,
              "balancedRoutes": 0,
              "optimizationCriterion": 0,
              "arrangeCriterion": 0,
              "optimizationQuality": 2,
              "maxTimeToOptimize": 300,
              "maxWaitTime": 18000,
              "routeType": 0,
              "restrictions": 0,
              "distanceUnit": 0,
              "orderSequenceOptions": []
            },
            "creationTimestamp": 1744096603789,
            "matrixBuildType": 1
          },
          "route": {
            "id": 255145,
            "optimizationId": 139950,
            "configurationParameters": {
              "name": "Paris - test optimization",
              "ignoreTimeWindow": false,
              "allowDroppingOrders": false,
              "groupingOrders": false,
              "balancedRoutes": 0,
              "optimizationCriterion": 0,
              "arrangeCriterion": 0,
              "optimizationQuality": 2,
              "maxTimeToOptimize": 300,
              "maxWaitTime": 18000,
              "routeType": 0,
              "restrictions": 0,
              "distanceUnit": 0,
              "orderSequenceOptions": []
            },
            "vehicleConstraints": {
              "fuelPrice": 1.0700000524520874,
              "startDate": 1596758400000,
              "maxNumberOfPackages": 53,
              "minNumberOfOrders": 0,
              "maxNumberOfOrders": 99999999,
              "minDistance": 0,
              "maxDistance": 100000000,
              "maxRevenue": 85
            },
            "rideStatus": 1,
            "vehicle": {
              "id": 139812,
              "type": 0,
              "status": 0,
              "name": "Car vehicle",
              "manufacturer": "",
              "model": "",
              "fuelType": 2,
              "lastPosition": [
                2147483647,
                2147483647
              ],
              "consumption": 6.5,
              "plate": "",
              "maxLoadWeight": 60,
              "maxLoadCube": 50,
              "height": 0,
              "width": 0,
              "weight": 0,
              "length": 0,
              "axleLoad": 0,
              "fixedCost": 0,
              "costPerHour": 420,
              "startTime": 1439,
              "endTime": 1439
            },
            "departure": {
              "depotId": 0,
              "alias": "Departure1",
              "location": [
                48.870569,
                2.356448
              ],
              "address": {
                "country": "France",
                "state": "",
                "county": "Nouvelle-Aquitaine",
                "city": "Poitiers",
                "postalCode": "86000",
                "streetName": "Boulevard Chasseigne",
                "streetNumber": "34"
              },
              "matchedLocation": [
                2147483647,
                2147483647
              ],
              "numberOfPackages": 0,
              "weight": 0,
              "cube": 0,
              "timeToNext": 0,
              "distanceToNext": 0,
              "departureTime": 0
            },
            "destination": {
              "depotId": 0,
              "alias": "Departure2",
              "address": {
                "country": "France",
                "state": "",
                "county": "Nouvelle-Aquitaine",
                "city": "Poitiers",
                "postalCode": "86000",
                "streetName": "Boulevard Chasseigne",
                "streetNumber": "34"
              },
              "location": [
                48.82674,
                2.342116
              ],
              "matchedLocation": [
                48.82679375,
                2.3420853125
              ],
              "arrivalTime": 1596783691000,
              "traveledDistance": 0.6638350486755371
            },
            "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW",
            "creationTimestamp": 1744096606089,
            "neededFuel": 0.04314928129315376,
            "matrixBuildType": 1,
            "price": 0.04616973176598549,
            "totalWaitTime": 0,
            "totalServiceTime": 0,
            "orders": [
              {
                "orderInfo": {
                  "id": 933799,
                  "creationTimestamp": 1744096603223,
                  "customerInfo": {
                    "id": 1839506,
                    "alias": "",
                    "firstName": "",
                    "lastName": "",
                    "address": {
                      "country": "",
                      "state": "",
                      "county": "",
                      "city": "",
                      "postalCode": "",
                      "streetName": "",
                      "streetNumber": ""
                    },
                    "email": "c1@yahoo.com",
                    "phoneNumber": "+12025550181",
                    "location": [
                      48.827327,
                      2.342267
                    ],
                    "customData": ""
                  },
                  "location": [
                    48.827327,
                    2.342267
                  ],
                  "alias": "",
                  "firstName": "",
                  "lastName": "",
                  "address": {
                    "country": "",
                    "state": "",
                    "county": "",
                    "city": "",
                    "postalCode": "",
                    "streetName": "",
                    "streetNumber": ""
                  },
                  "phoneNumber": "+12025550181",
                  "customData": "",
                  "type": 0,
                  "status": 0,
                  "state": 1,
                  "priority": 0,
                  "numberOfPackages": 0,
                  "weight": 0,
                  "cube": 0,
                  "revenue": 0,
                  "timeWindow": [
                    420,
                    1086
                  ],
                  "serviceTime": 0,
                  "depotId": 0
                },
                "matchedLocation": [
                  48.82734625,
                  2.3421875
                ],
                "actualLocation": [
                  0,
                  0
                ],
                "indexInRoute": 0,
                "indexInOptimization": 1,
                "arrivalTime": 1596783612000,
                "timeToNextOrder": 79,
                "waitTime": 0,
                "numberOfPackagesAtArrival": 0,
                "collectedNumberOfPackages": 0,
                "deliveredNumberOfPackages": 0,
                "weightAtArrival": 0,
                "collectedWeight": 0,
                "deliveredWeight": 0,
                "cubeAtArrival": 0,
                "collectedCube": 0,
                "deliveredCube": 0.07019499689340591,
                "traveledDistance": 0.5936400294303894,
                "distanceToNextOrder": 0,
                "revenueAtArrival": 0
              }
            ],
            "totalTime": 91
          }
        }
      ]
    }
  ]
}
Last updated on