NAV
shell

Introduction

This document is the official reference for the OptimoRoute Web Service Application Programming Interface (WS API).

Our Web Service API is HTTP based

The methods to retrieve data from our Web Service (WS) API require an HTTP GET request method.

The methods that submit, change, or destroy data require a POST request method.

The API methods will return an error if you do not make your request with the correct HTTP method.

We use JSON for structured data exchange

Our API uses the JSON (JavaScript Object Notation) format.

More information about JSON and how it works can be found here: http://json.org/ and here: http://en.wikipedia.org/wiki/JSON.

There are many readily available libraries to convert to and from the JSON format both for popular and for more esoteric programming languages.

SSL is required

Using SSL (https) is required to avoid passing both the authentication key and potentially confidential data in clear text over the web.

Limited number of concurrent requests

The maximum number of concurrent web service API requests for one account or for one IP address is limited to 5.

General error codes

The following error codes are applicable to all API operations:

Error Code Description
AUTH_KEY_MISSING the authentication key is missing
AUTH_KEY_UNKNOWN a wrong authentication key was supplied
MALFORMED_REQUEST something is wrong with the input
ERR_MISSING_MAND_FIELD one of the mandatory fields is missing
ERR_INVALID_PARAM_FORMAT one of the specified fields is not in a valid format
ERR_TOO_MANY_CONNECTIONS there are too many concurrent requests
ERR_INTERNAL an internal server error occur

There are also error codes specific that are described in the Error and Warning Codes section of each method.

Error codes with bulk operations

For bulk operations, there are multiple failure modes. For example, if performing a bulk operation on orders:

Allow for additional fields in the response messages

Additional fields might be added to the JSON response messages in the future, so your client code should ignore additional fields.  

Authentication

The OptimoRoute Web Service API authentication key parameter is required with all API requests, in addition to all the standard parameters.

To enable the API and generate the API key please log into the OptimoRoute web application. In the Administration section select Settings -> WS API and enable the API. The API key will be generated for you.

The Web Service API is also available during the free trial period.

Data Objects

Some endpoints in the API share definitions of objects that are sent in the request and response.

Order Object

Example Order Object

{
  "orderNo": "ORD001",
  "id": "6671978a86b19d18c69cc934315cb100",
  "date": "2018-11-12",
  "duration": 60,
  "priority": "M",
  "type": "T",
  "load1": 1,
  "load2": 0,
  "load3": 0,
  "load4": 0,
  "assignedTo": {"externalId": "DRV001", "serial": "001"},
  "location": {
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationName": "Green Cross Pharmacy North End",
    "latitude": 42.365142,
    "longitude": -71.052882,
    "checkInTime": 0,
    "notes": ""
  },
  "timeWindows": [{
      "twFrom": "11:00",
      "twTo": "17:00"
  }],
  "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
  "allowedDates": {},
  "allowedDateTimes": [{
      "from": "2019-12-10T07:39:00",
      "to": "2019-12-15T19:39:00"
  }],
  "skills": ["SK001"],
  "vehicleFeatures": [],
  "notes": "",
  "email": "john.doe@example.com",
  "phone": "",
  "customField1": "",
  "customField2": "",
  "customField3": "",
  "customField4": "",
  "customField5": "",
  "notificationPreference": "email"
}
Property Type Description
id string The read-only unique identifier of the order, assigned by OptimoRoute. If this property is sent in requests, it will be used to find the order to update, delete or retrieve, taking priority over orderNo.
orderNo string A user specified order identifier, also displayed in the web application. If id is not used in the WS API requests, orders are matched by this identifier, and it can be used to update, delete or retrieve orders.
relatedOrderNo string or null orderNo of the related order. Used to link pickups and deliveries in situations where goods are transported directly from one customer location to another customer location.
When creating orders, the relationship should be specified only on the second order that is created (the first order has to already exist in the system so that it can be referenced).
The default value is null, which means the order is not related to any other pickup/delivery.
relatedId string or null id of the related order. See relatedOrderNo above for related orders details.
date date (string) Order date.
YYYY-MM-DD format, for example 2013-12-20.
location location object Delivery/Service location. See Location Object.
type string enum Order type: D (delivery), P (pickup) or T (task).
duration decimal The time in minutes required to unload the goods or perform a task at the given location.
timeWindows list of time windows List of time windows when the order can be serviced.
Each time window is an object with twFrom and twTo fields. Both times are in 24-hour (military) clock format, in the range from 00:00 to 23:59.
twFrom specifies the earliest time allowed to begin the service (if the driver arrives too early, they will be forced to wait). twTo specifies the deadline to end the service.
Example:
[{"twFrom": "10:00", "twTo": "14:00"}].
Default is [] meaning no time windows.
allowedWeekdays list of strings Restricts days of the week when the order can be scheduled:
sun, mon, tue, wed, thu, fri, sat.
For example if the order can be scheduled on Monday or Tuesday the value should be:
["mon", "tue"].
By default all days of the week are allowed.
allowedDates daterange object Restricts the dates when the order can be scheduled.
Daterange is specified as an object with from and to fields, for example:
{"from": "2018-06-01", "to": "2018-07-01"}
Default is an empty object {} meaning no restriction.
allowedDateTimes list of datetime windows List of datetime windows when the order can be serviced.
Each object can contain from and/or to fields, which are datetime strings, or null. Strings are in the format YYYY-MM-DDTHH:MM:SS, e.g. 2020-01-30T15:54:02. The field from defines the earliest time to begin the service, and to defines the latest time to begin the service. When only one end of the restriction is given, the other is assumed to be null, meaning it is not restricted.
Example:
[{"from": "2019-12-26T00:00:00", "to": "2019-12-31T23:59:59"}].
Default is [] meaning no restriction.
assignedTo object or null An object with string properties serial or externalId that uniquely identifies the Driver that this Order must be assigned to. Example: {"serial": "102"} or {"externalId": "444"}. Setting this field forces this Order to be served by the specified Driver. A null value means no assignment, which is the default.
priority string Order priority, by default M. Values can be:
L – Low
M – Medium
H – High
C – Critical
High priority orders are scheduled earlier and are less likely to be left unscheduled if not all orders can be serviced.
load1 decimal The load requirements of the order, i.e. how many load units (Number of boxes, Kilos, Pounds, Liters etc) should be delivered.
The meaning of this entry depends on the provided configuration of load/capacity constraints.
Default value is 0.
load2 decimal See load1.
load2 decimal See load1.
load3 decimal See load1.
vehicleFeatures list of strings The vehicle features used to differentiate some Vehicles from the others. The required vehicle features are defined as a list of vehicle feature codes. Default value is an empty list [].
skills list of strings The driver skills used to differentiate some Drivers from the others. The required skills are defined as a list of skill codes. Default value is an empty list [].
notes string The optional note that will accompany the driver’s instructions. Notes do not affect the optimization process. A free form string.
customField1 string Value that will be saved in custom field #1, default empty.
customField2 string Value that will be saved in custom field #2, default empty.
customField3 string Value that will be saved in custom field #3, default empty.
customField4 string Value that will be saved in custom field #4, default empty.
customField5 string Value that will be saved in custom field #5, default empty.
email string Customer email. If enabled, order notifications can be sent to that email. Default empty.
phone string Customer phone number. Default empty.
notificationPreference string enum Defines the delivery method for order tracking notifications for this order. Notifications will only be sent if this account has order tracking configured.
Allowed values:
• dont_notify – don't send notifications
• email – send notification to email address specified in the email field
• sms – send text message to number specified in the phone field
• both – send both email and sms notifications
Defaults to both.
barcode list of barcode objects
optional		 List of barcodes attached to the order.
Each barcode is an object with a barcode field. The value is an arbitrary string.
Example:
[{"barcode": "12345678"}].
If there are no barcodes attached to the order, the result will return an empty array. Only present if Proof of Delivery feature is available.

Location Object

Location Object example with GPS coordinates:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "latitude": 39.9892,
  "longitude": -83.0054,
  "locationName": "Colorado pharmacy 033",
  "locationNo": "COL033",
  "valid": true,
  "notes": "GATE CODE 4412",
  "checkInTime": 3
}
Property Type / Default Description
locationNo string The unique identifier for the given location.
locationName string Location name.
address string The full address including the country, for example 393 Hanover St, Boston, MA 02113, US
latitude decimal Location latitude.
longitude decimal Location longitude.
valid boolean Read-only property, used only in responses. If found in a request it will be ignored. Returns true when the location is valid. Returns false when the location is invalid. Invalid locations are the ones that have no known latitude and longitude (e.g. they were created by specifying an address that could not be geocoded).
By default, when creating orders and locations the system will not accept erroneous or incomplete addresses and will raise an error. Using storeInvalid flag (from additional location object parameters in create order request) prevents raising an error and enables storing invalid locations and related orders in OptimoRoute. This way the problematic addresses can be corrected in OptimoRoute, however, orders with invalid locations cannot be a part of a plan until those location are corrected.
Invalid locations will have latitude and longitude properties present in the response but their values should not be considered.
checkInTime integer Default value is 0. Minimum waiting time at the location (in minutes). Upon arrival at the location the driver will spend at least checkInTime minutes before starting the service of one or several consecutive orders at the same location.
Example: if we have 3 orders at the same location:
  • A: duration 10min, check in time 15min
  • B: duration 5min, check in time 15min
  • C: duration 20min, check in time 15min
If one driver serves all three orders consecutively the driver would arrive at the location, spend 15 minutes at the location (for example parking and checking in) and then start servicing orders A, B and C. Total time at the location would be 50min = 15min (shared duration) + 10min (order A) + 5min (order B) + 20min (order C).
notes string Optional notes related to this location.

SelectedDriver Object

Use either driverExternalId or driverSerial (one field is enough):

Property Type / Default Description
driverExternalId
optional		 string
-		 The external identifier assigned to the driver in driver administration.
driverSerial
optional		 string
-		 The driver’s serial number.

Time object

Property Type Description
unixTimestamp
mandatory		 integer Number of seconds elapsed since 00:00 UTC January 1st 1970.
utcTime
mandatory		 ISO 8601 date (string) The UTC date and time
localTime
mandatory		 ISO 8601 date (string) The local time

The fields unixTimestamp, utcTime and localTime all refer to the same moment, so you can use whichever is more convenient.

Create Order

Creates a new order in the system or updates an existing order.

HTTP Request

POST https://api.optimoroute.com/v1/create_order

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_order?key=AUTH_KEY'

Parameters

Request body example:

{
  "operation": "CREATE",
  "orderNo": "ORD001",
  "type": "D",
  "date": "2014-10-14",
  "location": {
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationNo": "LOC001",
    "locationName": "Green Cross Pharmacy North End",
    "acceptPartialMatch": true
  },
  "duration": 20,
  "twFrom": "10:00",
  "twTo": "10:59",
  "load1": 10,
  "load2": 25,
  "vehicleFeatures": ["FR"],
  "skills": ["SK001", "SK002"],
  "notes": "Deliver at back door"
}

In addition to properties from the Order Object, the following properties are available:

Property Type Description
operation string enum CREATE – creates a new order in the system.

UPDATE – updates an existing order in the system. If the order does not exist the system will return an error.

SYNC – recommended when the end goal is to make sure orders are reflected in OptimoRoute. If this is a new order, we will create it. If there is an existing order in the system, it will be updated. SYNC makes a clean sync-up of order data. Whatever we have on this order will be replaced by the data you send us on SYNC.

MERGE – used to only update specific fields and leave all the other fields unchanged (for example if some fields were manually edited in OptimoRoute and should not be updated). If this is a new order, we will create it. If there is an existing order in the system, it will be updated.

For operations other than CREATE, the order will be looked up by its unique id if used in request, or orderNo if id is not used.
acceptDuplicateOrderNo boolean If set to true the system will accept orders with orderNo that already exists in the system. When false or not specified, the system will return an error.
twFrom time (string) Deprecated, please use the timeWindows field; ignored if timeWindows is set.

The earliest time allowed to begin the service (if the driver arrives too early, they will be forced to wait).
24-hour (military) clock format, for example: 16:00
The valid values range from 00:00 to 23:59.
twTo time (string) Deprecated, please use the timeWindows field; ignored if timeWindows is set.

The deadline to end the service.
24-hour (military) clock format, for example 17:00
The valid values range from 00:00 to 23:59.

The operation property is mandatory. When operation is specified as UPDATE, one of orderNo or id are mandatory, otherwise mandatory properties are date, type, duration, location and one of orderNo or id.

Location Object

Location Object example specifying address to be geocoded and accepting any result:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "acceptPartialMatch": true,
  "acceptMultipleResults": true
}

In addition to properties from the Location Object, the following properties are available:

Property Type Description
acceptMultipleResults boolean Used only if a new location is created by geocoding the address field. If false or not specified, the system will not accept the geocoded addresses where several results matching the provided address have been found and an error will be raised.
acceptPartialMatch boolean Used only if a new location is created by geocoding the address field. If false or not specified, the system will not accept the geocoded addresses that were only a partial match (lower geocoding confidence) and an error will be raised.
storeInvalid boolean Used only if a new location is created by geocoding the address field. If false or not specified, the system will raise an error when provided address is erroneous or incomplete (no address matching the provided one have been found). Setting this parameter to true enables storing incomplete location information that can be fixed afterwards. Until the location is corrected, planning orders with this location will not be possible.

A location is defined by one of the following:

Response

Response to example request:

{
  "success": true,
  "id": "8cde6711026ff11f79f15a719277fe26",
  "location": {
    "notes": "",
    "longitude": -71.0528824,
    "locationName": "Green Cross Pharmacy North End",
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "latitude": 42.3651425,
    "valid": true,
    "checkInTime": 0
  },
  "geocodingResults": [
    [
      "393 Hanover St, Boston, MA 02113, USA",
      42.3651425,
      -71.0528824
    ]
  ]
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if the order was saved, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
id
optional		 string
-		 The read-only unique identifier of the order, assigned by OptimoRoute
location
optional		 location object
-		 The location data for the created order (only if the operation was successful).
geocodingResults
optional		 list
-		 The list of geocoding results if the location is created from the supplied address.
Each geocoding result is defined as:
[geocodedAddress, latitude, longitude, partialMatchFlag]

Error and Warning Codes

The following error codes are applicable to Create Order method:

Error Code Description
ERR_ORD_EXISTS an order with the specified orderNo already exists in the system (checked only if orderNo field is set)
ERR_RELATED_ORD_MISSING the order with the ID passed in relatedOrderNo does not exist
ERR_RELATED_ORD_MULTIPLE multiple orders with ID passed in relatedOrderNo exist
ERR_RELATED_ORD_LINK order can not be linked to order with ID passed in relatedOrderNo (only pickups and deliveries can be linked)
ERR_DRV_NOT_EXISTS the driver with the serial number passed in assignedTo does not exist
ERR_DRV_MULTIPLE there is more than one driver with the assignedTo serial number
ERR_LOC_NOT_VALID the specified location is not valid
ERR_LOC_GEOCODING the specified address could not be geocoded
ERR_LOC_GEOCODING_MULTIPLE multiple results have been found during geocoding
ERR_LOC_GEOCODING_PARTIAL the geocoder did not return an exact match for the original request
ERR_LOC_NON_EXISTING_LOC the location specified by locationNo does not exist
ERR_LOC_MULTIPLE_LOC multiple locations with specified locationNo have been found
ERR_VF_NOT_EXISTS the vehicle feature does not exist (for one of the codes specified in vehicleFeatures field)
ERR_VF_MULTIPLE multiple vehicle features exist (for one of the codes specified in the vehicleFeatures field)
ERR_SK_NOT_EXISTS the skill does not exist (for one of the codes specified in the skills field)
ERR_SK_MULTIPLE multiple skills exist (for one of the codes specified in skills field)
WAR_LOC_GEOCODING the specified address could not be geocoded (but the order was created because storeInvalid was set to True)
WAR_LOC_GEOCODING_MULTIPLE multiple results have been found during geocoding (but the order was created because acceptMultipleResults was set to True)
WAR_LOC_GEOCODING_PARTIAL the geocoder did not return an exact match for the original request (but the order was created because acceptPartialMatch was set to True)

Create or Update Orders (bulk)

Create, update or replace one or more orders in the system.

Note that geocoding addresses is not available in this call. The locations for orders must either exist in the system, or be specified via latitude and longitude coordinates. Geocoding is available in Create Order.

HTTP Request

POST https://api.optimoroute.com/v1/create_or_update_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_or_update_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "54913250",
      "date": "2019-03-22",
      "duration": 60,
      "priority": "H",
      "type": "T",
      "assignedTo": {"externalId": "DRV001", "serial": "001"},
      "location": {
        "locationNo": "G402333",
        "address": "393 Hanover St, Boston, MA 02113, USA",
        "locationName": "Green Cross Pharmacy North End",
        "latitude": 42.365142,
        "longitude": -71.052882,
        "checkInTime": 0,
      },
      "timeWindows": [{
        "twFrom": "11:00",
        "twTo": "17:00"
      }],
      "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
      "allowedDates": {},
      "skills": ["SK001"],
      "vehicleFeatures": [],
      "notes": "Notify manager",
      "email": "joe.customer@example.com",
      "phone": "",
      "customField1": "300",
      "notificationPreference": "email"
    },
    {
      "orderNo": "27463225",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "locationNo": "999999999",
      },
    },
    {
      "orderNo": "09463221",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "notes": "",
        "locationNo": "R384892",
        "locationName": "Moe's Southwest Grill",
        "longitude": -71.7520717,
        "latitude": 42.2752323,
        "notes": "Use gate"
      },
    }
  ]
}
Property Type / Default Description
orders
mandatory		 list of order objects
-		 List of one or more order objects to create, update or replace in the system. At most 500 orders can be specified.

Order Object

In addition to properties from the Order Object, the following properties are available:

Property Type Description
operation string enum MERGE – used to only update specific fields and leave all the other fields unchanged (for example if some fields were manually edited in OptimoRoute and should not be updated). If this is a new order, we will create it. If there is an existing order in the system, it will be updated.

SYNC – recommended when the end goal is to make sure orders are reflected in OptimoRoute. If this is a new order, we will create it. If there is an existing order in the system, it will be updated. SYNC makes a clean sync-up of order data. Whatever we have on this order will be replaced by the data you send us on SYNC.

CREATE – creates a new order in the system; not allowed together with id

UPDATE – updates an existing order in the system. If the order does not exist the system will return an error.
acceptDuplicateOrderNo boolean If set to true the system will allow CREATE of orders with orderNo that already exists in the system. When false or not specified, the system will return an error.

Each order object given in orders will result in an order being created, updated or replaced in the system. The exact behavior for each order can be configured via operation in each order object. The default behavior is:

Location Object

See Location Object for all available location properties. Locations can be created or updated.

If locationNo is specified and a matching location exists, that location will be updated. If locationNo does not have any matches, a new location will be created.

If locationNo is not specified and an existing order is updated - the order's location will be updated.

During update, the matched location will be updated with the values given in the object, if any. No properties are mandatory when updating. When updating with SYNC the properties are reset to default, otherwise they keep their existing values.

In cases when a new location is created, the following properties are mandatory: latitude, longitude and one of locationNo, address, locationName.

Response

Response example:

{
  "orders": [
    {
      "success": true,
      "id": "c821486835d2f20539a9754454f7efbe",
      "orderNo": "54913250"
    },
    {
      "success": false,
      "code": "ERR_LOC_NON_EXISTING_LOC",
      "message": "The location with the given location number does not exist.",
      "orderNo": "27463225",
      "locationNo": "999999999"
    },
    {
      "success": true,
      "id": "8cde6711026ff11f79f15a719277fe26",
      "orderNo": "09463221"
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if at least one operation was successful, false if all failed
orders
 list of order response objects
-		 Each order object in the list corresponds to the respective order in the request. See Order Response Object section for more information.

Order Response Object

Property Type / Default Description
success
mandatory		 boolean
-		 true if the operation succeeded, false if there was an error.
orderNo
optional		 string
-		 Identifier of the respective order
id
optional		 string
-		 The read-only unique identifier of the order, assigned by OptimoRoute
locationNo
optional		 string
-		 Identifier of the location if a location-related error happened
code
optional		 string
-		 A per-order error code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).

Error and Warning Codes

The following per-order error codes are applicable:

Error Code Description
ERR_INVALID_PARAM_FORMAT the specified order is not valid, possibly an order to be created/updated did not exist in the system but could not be created because a mandatory property is missing
ERR_ORD_EXISTS an order with the specified orderNo already exists in the system (only with CREATE plus orderNo)
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found (only with UPDATE plus orderNo, or if using id in the request)
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_OPT_RUNNING optimization is running for this order
ERR_RELATED_ORD_MISSING the order with the orderNo passed in relatedOrderNo does not exist
ERR_RELATED_ORD_MULTIPLE multiple orders with orderNo passed in relatedOrderNo exist
ERR_RELATED_ORD_LINK order can not be linked to order with orderNo passed in relatedOrderNo (only pickups and deliveries can be linked)
ERR_DRV_NOT_EXISTS the driver specified in assignedTo does not exist
ERR_DRV_MULTIPLE there is more than one driver with the specified assignedTo values
ERR_LOC_NOT_VALID the specified location is not valid, possibly a location to be created/updated did not exist in the system but could not be created because a mandatory property is missing
ERR_LOC_NON_EXISTING_LOC the location specified by locationNo does not exist
ERR_LOC_MULTIPLE_LOC multiple locations with specified locationNo have been found
ERR_VF_NOT_EXISTS the vehicle feature does not exist (for one of the codes specified in vehicleFeatures field)
ERR_VF_MULTIPLE multiple vehicle features exist (for one of the codes specified in the vehicleFeatures field)
ERR_SK_NOT_EXISTS the skill does not exist (for one of the codes specified in the skills field)
ERR_SK_MULTIPLE multiple skills exist (for one of the codes specified in skills field)

Get Orders (bulk)

Retrieves one or more orders from the system.

HTTP Request

POST https://api.optimoroute.com/v1/get_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Property Type / Default Description
orders
mandatory		 list of order objects
-		 List of order objects to retrieve. Each order object can contain either of:
  • orderNo: the user-specified identifier of an order
  • id: the unique identifier of the order, assigned by OptimoRoute
At most 500 orders can be specified.



For flexibility, if using only orderNo the call to get_orders can also be done as a HTTP GET request:

GET request example:

curl 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99'
Property Type / Default Description
orderNo
mandatory		 string
-		 The user-specified identifier of an order; can be repeated to retrieve multiple orders

Response

Response example:

{
  "success": true,
  "orders": [
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d",
      "data": {
        "orderNo": "ORD001",
        "id": "04e7b09e993e8488024f46aaf9d8c72d",
        "date": "2018-11-12",
        "duration": 60,
        "priority": "M",
        "type": "T",
        "load1": 1,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "assignedTo": {"externalId": "DRV001", "serial": "001"},
        "location": {
          "locationNo": "LOC001",
          "address": "393 Hanover St, Boston, MA 02113, USA",
          "locationName": "Green Cross Pharmacy North End",
          "latitude": 42.365142,
          "longitude": -71.052882,
          "checkInTime": 0,
          "notes": ""
        },
        "timeWindows": [{
            "twFrom": "11:00",
            "twTo": "17:00"
        }],
        "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
        "allowedDates": {},
        "skills": ["SK001"],
        "vehicleFeatures": [],
        "notes": "",
        "email": "",
        "phone": "",
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "notificationPreference": "email"
      }
    },
    {
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD99",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d",
      "data": {
        "orderNo": "-",
        "id": "04e7b09e993e8488024f46aaf9d8c72d",
        "date": "2018-11-12",
        "duration": 30,
        "priority": "M",
        "type": "T",
        "load1": 2,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "assignedTo": null,
        "location": {
          "locationNo": "LOC001",
          "address": "393 Hanover St, Boston, MA 02113, USA",
          "locationName": "Green Cross Pharmacy North End",
          "latitude": 42.365142,
          "longitude": -71.052882,
          "checkInTime": 0,
          "notes": ""
        },
        "timeWindows": [],
        "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
        "allowedDates": {},
        "skills": ["SK001"],
        "vehicleFeatures": [],
        "notes": "",
        "email": "",
        "phone": "",
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "notificationPreference": "email"
      }
    },
  ]
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if at least one order was retrieved, false if no orders were retrieved
orders
mandatory		 list of order response objects
-		 Each order object in the list corresponds to the respective orderNo and/or id in the request. See Order Response Object section for more information.

Order Response Object

Property Type / Default Description
success
mandatory		 boolean
-		 true if the order was retrieved, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
orderNo
optional		 string
-		 The orderNo whose retrieval failed. Only present if the operation was not successful and orderNo was used in the request.
id
mandatory		 string
-		 The unique identifier of the order, assigned by OptimoRoute.
data
optional		 Order object
-		 The retrieved order.

Order Object

In case of success, data will be an object with properties listed in Order Object.

The returned type property can additionally be break or depot.

Error and Warning Codes

The following per-order error codes are applicable to Get Orders method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo and/or id was not found.
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_INVALID_PARAM_FORMAT this orderNo is not valid

Delete Order

Removes an order from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_order

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_order?key=AUTH_KEY'

Parameters

Request body example:

{
  "orderNo": "ORD001"
}
Property Type / Default Description
orderNo
mandatory		 string
-		 The user-specified identifier of the order to be deleted.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if order was deleted, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
planningId
optional		 integer
-		 The id of the planning process in case optimization is running for this order.

Error and Warning Codes

The following error codes are applicable to Delete Order method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_OPT_RUNNING optimization is running for this order

Delete All Orders

Removes all orders and planned routes for the specified date from the system. If no date is set, all orders and routes are removed from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_all_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_all_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "date": "2014-10-14"
}
Property Type / Default Description
date
optional		 date (string)
-		 Date for which orders and routes will be deleted.
YYYY-MM-DD format, for example 2013-12-20.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if orders were deleted, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
planningId
optional		 integer
-		 The id of the planning process in case optimization is running.

Error and Warning Codes

The following error codes are applicable to Delete Order method:

Error Code Description
ERR_OPT_RUNNING optimization is running for this date

Delete Orders (bulk)

Removes one or more orders from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD999"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Property Type / Default Description
orders
mandatory		 list of order objects
-		 List of order objects to delete. Each order object can contain either of:
  • orderNo: the user-specified identifier of an order
  • id: the unique identifier of the order, assigned by OptimoRoute
At most 500 orders can be specified.
deleteMultiple
optional		 boolean
false		 If false, when there are multiple orders matched by one order object, an error will be returned. If true, all the matches will be deleted.

Response

Response example:

{
  "success": true,
  "orders": [
    {
      "orderNo": "ORD001",
      "success": true
    },
    {
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD999",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if at least one order was deleted, false if no orders were deleted.
orders
mandatory		 list of delete response objects
-		 Each order object in the list corresponds to the respective orderNo and/or id in the request. See Delete Response Object section for more information.

Delete Response Object

Property Type / Default Description
success
mandatory		 boolean
-		 true if deleted, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
orderNo
optional		 string
-		 The orderNo which was deleted, or whose delete failed. Only present if orderNo was used in the request.
id
optional		 string
-		 The id which was deleted, or whose delete failed. Only present if id was used in the request.
planningId
optional		 integer
-		 The id of the planning process in case optimization is running for this order.

Error and Warning Codes

The following per-order error codes are applicable to Delete Orders method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo and/or id was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo, but deleteMultiple was set to false
ERR_OPT_RUNNING optimization is running for this order
ERR_INVALID_PARAM_FORMAT this orderNo or id is not valid

Get Routes

Gets the routes for a specific date.

HTTP Request

GET https://api.optimoroute.com/v1/get_routes

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_routes?key=AUTH_KEY&date=2013-12-20'

curl 'https://api.optimoroute.com/v1/get_routes?key=AUTH_KEY&date=2022-03-16&driverSerial=011&includeRoutePolyline=true'

Parameters

Property Type / Default Description
date
mandatory		 date (string)
-		 Queried date.
YYYY-MM-DD format, for example 2013-12-20.
driverExternalId
optional		 string
-		 Optionally filter by drivers external identifier.
driverSerial
optional		 string
-		 Optionally filter by Serial number of the Driver.
vehicleRegistration
optional		 string
-		 Optionally filter by Vehicle registration.
includeRoutePolyline
optional		 boolean
false		 Optional property to include route polyline in the output. This polyline can be used to display the route on the map. The polyline is a list of coordinates encoded with Encoded Polyline Algorithm.

Response

Response example

{
  "success": true,
  "routes": [
    {
      "driverExternalId": "",
      "driverSerial": "011",
      "driverName": "Driver 011",
      "vehicleRegistration": "Vehicle 011",
      "vehicleLabel": "011",
      "duration": 37,
      "distance": 19.563,
      "load1": 0,
      "load3": 0,
      "load2": 0,
      "load4": 0,
      "stops": [
        {
          "stopNumber": 1,
          "orderNo": "-",
          "id": "f7afe58fcddfcbf9f42620c79ebad7ff",
          "scheduledAt": "10:16",
          "scheduledAtDt": "2022-03-16 10:16:41",
          "arrivalTimeDt": "2022-03-16 10:16:41",
          "address": "Burwyn, IL",
          "locationName": "Burwyn, IL",
          "locationNo": "",
          "latitude": 41.8505874,
          "longitude": -87.7936685,
          "distance": 0,
          "travelTime": 0
        },
        {
          "stopNumber": 2,
          "orderNo": "-",
          "id": "0a077bd652b4b0c69fd9bdb3efefe729",
          "scheduledAtDt": "2022-03-16 10:33:18",
          "arrivalTimeDt": "2022-03-16 10:33:18",
          "scheduledAt": "10:33",
          "address": "Oak Park, Chicago",
          "locationName": "Oak Park, Chicago",
          "locationNo": "",
          "latitude": 41.8850317,
          "longitude": -87.7845025,
          "distance": 4668,
          "travelTime": 397
        }
      ],
      "routePolyline": "_}l~FlezvO????Ag@?Y?U?s@?c@AgCAmB?w@?]?IAc@Hm@AoCAw@A}C?WA_AAsFCwD?M?m@CsF?k@AwAAw@?W?_@U?qA@S?U@[?gEDiIHm@?cJHmJFiJJoJFmJHqGFe@?u@@gA@Q?oGHuBBuFFmJLq@Bg@?}CD]@m@?k@@o@@i@?oGH}HHc@@M?O?a@@yDD}BBM?_GFY@Y?O?O@W?U@w@?Q@y@?uABwA@Q?S@kA@M?{EDQ@S?gHD??fHER?PAzEEL?jAARAP?vAAtACx@?PAv@?TAV?AYA{E?qACaDAkBAw@?oAAgA?WAqA?E?_@A]?WC}E?k@Ae@?M?[AwBAsB?o@AoA?g@Ai@?mAAsACkCA{DA{BA{BAo@?]CqF?G?e@Ae@?u@CcG?QEcF?O?m@?]A_F?QAy@?[PAX?J?^AH?FA~@AR?XA|@AhACP?R?tAChAAxAAh@A\\AR?RAd@?^AxACzAAvACr@Ad@AzAC~BAt@AN?RBPBfA?b@@f@?L?b@@^AtBQt@KEe@AMGw@c@mFa@wEOyCGoCQ}BMy^G}UC_ICwJC}JE_JIeHI_ICyBIqAMyAMmASsAWqA[mA_@kAo@iBm@{Aa@kA[cA]uAQu@Mw@QuAK}@IeAEcAC_ACcDAqGOwb@CsJCuKKc[AuDM_c@C_DCuASeF]uEWcD_@_F[wDo@uIUmDKsBIuBEsBGuCCqCAeFEkOGuQE}OC}HCkQCwM?wFC_SI{QCmEAwH@}FAmEGoNMqUAeEEcG?cC@sD?sB@mCB_EDkDBuBDeC@yBPuIDqGAyPAyECsBEsACyDAuB?u@?c@?sGCgCGkKC{BA_GAwB?S?u@AcD?Y?_A?yA@aA?s@B}AB{B?uB?]?eA?yC?OAkEAiB?_@?_AAmA?M]?]@G?G?}@Be@?yAB?F?bA?LM?aFFG?"
    }
  }
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if the query was successful, false if there was an error.
routes
mandatory		 list of route objects
[]		 List of routes matching the query.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).

Route Object

Property Type / Default Description
driverExternalId
mandatory		 string
-		 The drivers external identifier.
driverSerial
mandatory		 string
-		 The serial number assigned to the driver.
driverName
mandatory		 string
-		 The driver’s name.
vehicleRegistration
mandatory		 string
-		 Vehicle registration.
vehicleLabel
mandatory		 string
-		 Vehicle label.
duration
mandatory		 integer
-		 Route duration in minutes.
distance
mandatory		 decimal
-		 Route distance in kilometers.
load1
mandatory		 integer
0		 Route load #1.
load2
mandatory		 integer
0		 Route load #2.
load3
mandatory		 integer
0		 Route load #3.
load4
mandatory		 integer
0		 Route load #4.
stops
mandatory		 list of stop objects
[]		 An ordered list of stops/orders on the route.
routePolyline
optional		 string
-		 Route polyline encoded with Encoded Polyline Algorithm. Only included if includeRoutePolyline is set to True.

Stop Object

Property Type / Default Description
stopNumber
mandatory		 integer
-		 Stop number. Starts at 1.
orderNo
mandatory		 string
-		 The order number.
id
mandatory		 string
-		 The read-only unique identifier of the order, assigned by OptimoRoute.
locationNo
mandatory		 string
-		 Location number.
locationName
mandatory		 string
-		 Location name.
address
mandatory		 string
-		 Location address.
latitude
mandatory		 decimal
-		 Location latitude.
longitude
mandatory		 decimal
-		 Location longitude.
scheduledAt
mandatory		 time (string)
-		 The scheduled time to begin the service.
24-hour (military) clock format, for example: 16:00.
The valid values range from 00:00 to 23:59.
scheduledAtDt
mandatory		 datetime (string)
-		 The scheduled date and time to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
arrivalTimeDt
mandatory		 datetime (string)
-		 The date and time when the driver arrived at the location. Because of time windows the driver might need to wait to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
travelTime
mandatory		 integer
-		 Travel time from previous stop (in seconds).
distance
mandatory		 integer
-		 Distance from previous stop (in meters).
type
optional		 string
-		 Order type only added for lunch breaks (value will be break) and for depot trips (value will be depot).

Error and Warning Codes

None.

Get Scheduling Information

Gets the scheduling information for the specified Order. For bulk method see Search Orders

HTTP Request

GET https://api.optimoroute.com/v1/get_scheduling_info

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_scheduling_info?key=AUTH_KEY&orderNo=ORD001'

Parameters

Property Type / Default Description
orderNo
optional		 string
-		 The user-specified identifier for the order.
id
optional		 string
-		 The unique identifier of the order, assigned by OptimoRoute.

One of the two properties must be provided in the request.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if the query was successful, false if there was an error.
orderScheduled
optional		 boolean
-		 true if the order is scheduled, false otherwise.
scheduleInformation
optional		 schedule info object
-		 The order scheduling information.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).

Order Scheduling Information Object

Property Type / Default Description
driverExternalId
mandatory		 string
-		 The drivers external identifier.
driverSerial
mandatory		 string
-		 The serial number assigned to the driver.
driverName
mandatory		 string
-		 The driver’s name.
vehicleRegistration
mandatory		 string
-		 Vehicle registration.
vehicleLabel
mandatory		 string
-		 Vehicle label.
stopNumber
mandatory		 integer
-		 Stop number on the route. Starts at 1.
scheduledAt
mandatory		 time (string)
-		 The scheduled time to begin the service.
24-hour (military) clock format, for example: 16:00.
The valid values range from 00:00 to 23:59.
scheduledAtDt
mandatory		 datetime (string)
-		 The scheduled date and time to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
arrivalTimeDt
mandatory		 datetime (string)
-		 The date and time when the driver arrived at the location. Because of time windows the driver might need to wait to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
travelTime
mandatory		 integer
-		 Travel time from previous stop (in seconds).
distance
mandatory		 integer
-		 Distance from previous stop (in meters).

Error and Warning Codes

The following error codes are applicable to Get Scheduling Information method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo

Response example 1

{
  "success": true,
  "orderScheduled": true,
  "scheduleInformation": {
    "stopNumber": 23,
    "scheduledAt": "11:23",
    "scheduledAtDt": "2020-02-07 11:23:22",
    "arrivalTimeDt": "2020-02-07 11:23:22",
    "driverSerial": "005",
    "driverExternalId": null,
    "driverName": "Driver 005",
    "vehicleLabel": "005",
    "vehicleRegistration": "Vehicle 005",
    "distance": 952,
    "travelTime": 123
  }
}

Response example 2

{
    "success":true,
    "orderScheduled":false
}

Start Planning

Starts the planning process for the specified date.

HTTP Request

POST https://api.optimoroute.com/v1/start_planning

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/start_planning?key=AUTH_KEY'

Parameters

Request body example:

{
  "date": "2013-12-20"
}
Property Type / Default Description
date
mandatory		 date (string)
-		 Date to be planned.
YYYY-MM-DD format, for example 2013-12-20.
dateRange
optional		 daterange object Support for weekly planning (planning a longer time horizon). If dateRange is specified date is ignored and can be left out.
Daterange is specified as an object with from and to fields, for example:
{"from": "2020-04-27", "to": "2020-05-01"}.
balancing
optional		 string
OFF		 Route balancing settings. Allowed values:
OFF – No balancing
ON – Balance routes
ON_FORCE – Balance routes and use all drivers

No balancing: returns the best routes, some drivers might not be used.
Balance routes: balance the work load between drivers, some drivers may not be used.
Balance routes and use all drivers: balance work load between all available drivers.
balanceBy
optional		 string
WT		 If route balancing is turned on, this defines the criteria for balancing the routes.

Allowed values:
WT – Working time
NUM – Number of orders per driver
balancingFactor
optional		 decimal
0.3		 Importance of balancing compared to route costs. Increasing the balancing factor will result in more balanced routes.
Only applicable in combination with ON_FORCE (otherwise ignored).

Minimum value: 0.0
Maximum value: 1.0
startWith
optional		 string
EMPTY		 Start planning from existing routes or from scratch.

Allowed values:
EMPTY – Ignore existing routes and start from scratch
CURRENT – Start planning with the existing routes
lockType
optional		 string
NONE		 Applicable if startWith is set to CURRENT.

Allowed values:
NONE – Allow all changes to the existing routes
ROUTES - Keep planned Routes unchanged and add new Orders to unused
RESOURCES - Keep Drivers/Vehicles for planned Orders and fit in new Orders
depotTrips
optional		 boolean
false		 If true drivers will be scheduled to return to the warehouse to reload (or unload in case of pickups) if there is still time within their working hours to do another route.
More information is available on our blog:
https://optimoroute.com/stop-restock-and-continue-on-your-way/.
depotVisitDuration
optional		 integer
0		 Time in minutes required to reload or unload the goods in the warehouse before the driver goes out for another run.
Only applicable if depotTrips is set to true.
clustering
optional		 boolean
false		 If true the system will try to minimize overlapp between driver routes.
useDrivers
optional		 list of SelectedDriver objects
[]		 Selected drivers that should be used in the optimization.
By default (if useDrivers is not set or the list is empty) all available drivers for the specified date are used.
useOrders
optional		 list of strings
[]		 Deprecated in favor of useOrderObjects.
Selected orders that should be included in the optimization.
Orders are specified as a list of order identifiers (orderNo strings).
By default (if useOrders is not set or the list is empty) all orders for the specified date that have a valid location are included.

Orders that are not selected, but are already scheduled to drivers that will be used in the optimization will be unscheduled unless the includeScheduledOrders flag is set to true.
useOrderObjects
optional		 list of objects
[]		 Subset of orders on the planned date that should be included in the optimization.
Orders are specified as list of objects that can contain either of:
  • orderNo property with the user-specified identifier of an order
  • id unique identifier of the order as assigned by OptimoRoute

By default (if useOrderObjects is not set or the list is empty) all orders for the specified date that have a valid location are included.

Orders that are not selected, but are already scheduled to drivers that will be used in the optimization will be unscheduled unless the includeScheduledOrders flag is set to true.
includeScheduledOrders
optional		 boolean
true		 Determines behavior when a subset of orders is selected but there are other orders already scheduled to the applicable drivers.
If includeScheduledOrders is true, these orders will be included in the optimization, otherwise they will be unscheduled.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if the optimization was started, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
planningId
optional		 integer
-		 Returns id of the started optimization if operation was successful, or the already running optimization in case of ERR_OPT_RUNNING_FOR_DATE error. Planning id can be used later for getting the planning status or stopping the planning process.
missingOrders
optional		 list of strings
[]		 In case ERR_ORD_NOT_FOUND error is raised this field will contain the list of missing order identifiers (orderNo strings).
missingDrivers
optional		 list of SelectedDriver objects
[]		 In case ERR_DRIVER_NOT_FOUND error is raised this field will contain a list of missing drivers. Each driver is a SelectedDriver object.
ordersWithInvalidLocation
optional		 list of strings
[]		 In case ERR_ORD_WITH_INVALID_LOC error is raised this field will contain the list of order identifiers (orderNo strings) that have an invalid location.

Error and Warning Codes

The following error codes are applicable to Start Planning method:

Error Code Description
ERR_OPT_TRIAL_ENDED free trial has ended for this account
ERR_OPT_RUNNING_FOR_DATE planning is already running for this date
ERR_OPT_RUNNING_FOR_ORDER optimization is already running for one or more orders listed in useOrders
ERR_OPT_NO_REQUESTS no orders exist for the specified date
ERR_OPT_NO_RESOURCES no drivers are available for this date
ERR_OPT_RESOURCES_EXCEEDED number of driver exceeded
ERR_OPT_REQUESTS_EXCEEDED number of orders exceeded
ERR_OPT_COULD_NOT_START internal error, please contact support
ERR_ORD_NOT_FOUND one or more orders specified in useOrders were not found
ERR_ORD_WITH_INVALID_LOC one or more orders specified in useOrders have invalid location
ERR_DRIVER_NOT_FOUND one or more drivers specified in useDrivers were not found
ERR_MULTIPLE_ORD_FOUND multiple orders with specified identifier have been found
ERR_MULTIPLE_DRV multiple drivers with specified identifier have been found
ERR_UNSUPPORTED_BY_PRICING_PLAN weekly planning is only supported with the current plan
ERR_DATE_RANGE_TOO_LONG weekly planning range is too long
ERR_DATE_RANGE_INVALID invalid range, to date is earlier than from date

Stop Planning

Stops the planning process.

HTTP Request

POST https://api.optimoroute.com/v1/stop_planning

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/stop_planning?key=AUTH_KEY'

Parameters

Request body example:

{
  " planningId": 8828
}
Property Type / Default Description
planningId
mandatory		 integer
-		 The id of the planning process to be stopped.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if the optimization was stopped, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Stop Planning method:

Error Code Description
ERR_JOB_NOT_FOUND planning job with specified id was not found
ERR_OPT_NOT_RUNNING planning job is not running
ERR_OPT_COULD_NOT_STOP internal error, please contact support

Get Planning Status

Returns the status of the planning process.

HTTP Request

GET https://api.optimoroute.com/v1/get_planning_status

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_planning_status?key=AUTH_KEY&planningId=8828'

Parameters

Property Type / Default Description
planningId
mandatory		 integer
-		 The id of the planning process.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if the request was a success, false if an error occurred.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
status
optional		 string
-		 N - New
R - Running
C - Cancelled by the user
F - Finished
E - Error occurred
percentageComplete
optional		 integer
-		 Percentage complete – values range from 0 to 100.

Error and Warning Codes

The following error codes are applicable to Get Planning Status method:

Error Code Description
ERR_JOB_NOT_FOUND the planning job with the specified id was not found

Update Driver Parameters

Updates driver parameters for a particular date and driver start and end location. Any existing routes for the specified date/driver will be unscheduled.

The following parameters can be changed:

HTTP Request

POST https://api.optimoroute.com/v1/update_driver_parameters

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_driver_parameters?key=AUTH_KEY'

Parameters

Request body example:

{
  "externalId": "3945300304540",
  "date": "2019-09-25",
  "workTimeFrom": "09:30",
  "workTimeTo": "18:00"
}
Property Type / Default Description
externalId
mandatory		 string
-		 The external identifier assigned to the driver in driver administration.
date
mandatory		 date
-		 Date to be planned.
YYYY-MM-DD format, for example 2013-12-20.
enabled
optional		 boolean
unchanged		 Enable or disable driver for the specified date.
workTimeFrom
optional		 time (string)
unchanged		 Driver’s work time from for the specified date.
24-hour (military) clock format, for example: 08:00.
The valid values range from 00:00 to 23:59.
workTimeTo
optional		 time (string)
unchanged		 Driver’s work time end for the specified date.
24-hour (military) clock format, for example: 08:00. The valid values range from 00:00 to 23:59.
assignedVehicle
optional		 string
unchanged		 The external identifier of the vehicle to be assigned to the driver for the specified date. This will also update the vehicle load capacity parameters (unless they are overridden with vehicleCapacityX settings).
vehicleCapacity1
optional		 integer
unchanged		 The new vehicle load capacity #1 for the specified date.
vehicleCapacity2
optional		 integer
unchanged		 The new vehicle load capacity #2 for the specified date.
vehicleCapacity3
optional		 integer
unchanged		 The new vehicle load capacity #3 for the specified date.
vehicleCapacity4
optional		 integer
unchanged		 The new vehicle load capacity #4 for the specified date.
startLatitude
optional		 decimal
unchanged		 Driver’s start location GPS latitude will be changed (this new location will be used for all future optimizations). If startLongitude is not defined this value will be ignored.
startLongitude
optional		 decimal
unchanged		 Driver’s start location GPS longitude (this new location will be used for all future optimizations). If startLatitude is not defined this value will be ignored.
startAddress
optional		 string
unchanged		 Driver’s start location address that will be displayed on reports (this new location will be used for all future optimizations). If startLatitude and startLongitude are not defined this value will be ignored.
endLatitude
optional		 decimal
unchanged		 Driver’s end location GPS latitude (this new location will be used for all future optimizations). If endLongitude is not defined this value will be ignored.
endLongitude
optional		 decimal
unchanged		 Driver’s end location GPS longitude (this new location will be used for all future optimizations). If endLatitude is not defined this value will be ignored.
endAddress
optional		 string
unchanged		 Driver’s end location address that will be displayed on reports (this new location will be used for all future optimizations). If endLatitude and endLongitude are not defined this value will be ignored.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true if the driver parameters were updated, false if an error occurred.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Update Driver Parameters method:

Error Code Description
ERR_DRIVER_NOT_FOUND the driver with the specified externalId was not found
ERR_MULTIPLE_DRV multiple drivers with specified externalId have been found
ERR_VEH_NOT_FOUND the vehicle with the specified externalId was not found
ERR_MULTIPLE_VEH multiple vehicles with specified externalId have been found

Update Driver Parameters (bulk)

Updates parameters of multiple drivers for the specified dates. Any existing routes for the specified drivers and dates will be unscheduled.

The following parameters for particular dates can be changed:

HTTP Request

POST https://api.optimoroute.com/v1/update_drivers_parameters

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_drivers_parameters?key=AUTH_KEY'

Parameters

Request body example:

{
  "updates": [
    {
      "driver": {
        "externalId": "001"
      },
      "date": "2022-02-15",
      "workTime": {
        "from": "08:15",
        "to": "16:15"
      },
      "vehicleCapacity1": 100,
      "startLocation": {
        "type": "custom",
        "latitude": 45.805945,
        "longitude": 16.237825
      },
      "endLocation": {
        "type": "startLocation"
      }
    },
    {
      "driver": {
        "serial": "S001"
      },
      "date": "2022-02-16",
      "workTime": {
        "from": "09:00",
        "to:": "17:00"
      },
      "assignedVehicle": {
        "registration": "VEH001"
      },
      "endLocation": {
        "type": "employeeDefault"
      }
    }
  ]
}
Property Type / Default Description
updates
mandatory		 list of driver parameters objects
-		 List of one or more driver parameters objects to update in the system. At most 500 driver parameters objects can be specified.

DriverParameters Object

Property Type / Default Description
driver
mandatory		 object
-		 An object with string properties serial or externalId that uniquely identifies the Driver. Example: {"serial": "102"} or {"externalId": "444"}.
date
mandatory		 date
-		 Date to be planned.
YYYY-MM-DD format, for example 2013-12-20.
enabled
optional		 boolean
unchanged		 Enable or disable driver for the specified date.
workTime
optional		 WorkTime object
unchanged		 Driver’s work time from/to for the specified date.
assignedVehicle
optional		 string or object
unchanged		 The external identifier as a string or an object with string properties registration or externalId that uniquely identifies the Vehicle to be assigned to the driver for the specified date. This will also update the vehicle load capacity parameters (unless they are overridden with vehicleCapacityX settings). Example: V103 or {"registration": "444"} or {"externalId": "V103"}.
vehicleCapacity1
optional		 integer
unchanged		 The new vehicle load capacity #1 for the specified date.
vehicleCapacity2
optional		 integer
unchanged		 The new vehicle load capacity #2 for the specified date.
vehicleCapacity3
optional		 integer
unchanged		 The new vehicle load capacity #3 for the specified date.
vehicleCapacity4
optional		 integer
unchanged		 The new vehicle load capacity #4 for the specified date.
startLocation
optional		 LocationType object
unchanged		 Driver’s start GPS location (this location will be used for future optimizations for specified date). Location type startLocation can't be used.
endLocation
optional		 LocationType object
unchanged		 Driver’s end GPS location (this location will be used for future optimizations for specified date).

When locationType is custom and there is no location with the same latitude, longitude and address, a new location will be created and visible in the location administration. The location name will be the same as the address if defined, otherwise the name is generated from latitude and longitude.

WorkTime Object

Property Type / Default Description
from
mandatory		 time (string)
-		 Driver’s work time from.
24-hour (military) clock format, for example: 08:00.
The valid values range from 00:00 to 23:59.
to
mandatory		 time (string)
-		 Driver’s work time end.
24-hour (military) clock format, for example: 08:00. The valid values range from 00:00 to 23:59.

LocationType Object

Property Type / Default Description
type
mandatory		 string enum custom – location latitude, longitude and address will be used.

employeeDefault – employee's default location will be used.

startLocation – employee's start location will be used.
address
optional		 string
-		 Location address that will be displayed on reports, for example 393 Hanover St, Boston, MA 02113, US.
latitude
optional		 decimal
-		 Location latitude.
longitude
optional		 decimal
-		 Location longitude.

The type property is mandatory. When type is specified as create, mandatory properties are latitude and longitude, otherwise only type should be defined.

Response

Response example:

{
  "updates": [
    {
      "success": true,
      "driver": {
        "externalId": "005"
      },
      "date": "2022-02-15"
    },
    {
      "success": false,
      "driver": {
        "serial": "S002"
      },
      "date": "2022-02-16",
      "code": "ERR_LOC_NOT_VALID",
      "message": "Location is not valid.",
    },
    {
      "success": false,
      "driver": {
        "externalId": "003"
      },
      "date": "2022-02-17",
      "code": "ERR_DRIVER_NOT_FOUND",
      "message": "Could not find a driver with the matching id",
    },
    {
      "success": false,
      "driver": {
        "externalId": "010"
      },
      "date": "2022-02-18",
      "code": "ERR_MULTIPLE_DRV",
      "message": "Found multiple drivers with matching external id or serial number.",
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if at least one operation was successful, false if all failed
updates
 list of driver response objects
-		 Each driver object in the list corresponds to the respective driver in the request. See Driver Response Object section for more information.

Driver Response Object

Property Type / Default Description
success
mandatory		 boolean
-		 true if the operation succeeded, false if there was an error.
driver
optional		 object
-		 Identifier of the respective driver as an object with string properties serial or externalId.
date
optional		 date
-		 Date associated with the respective driver.
code
optional		 string
-		 A per-order error code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Update Drivers Parameters method:

Error Code Description
ERR_DRIVER_NOT_FOUND the driver with the specified externalId or serial was not found
ERR_MULTIPLE_DRV multiple drivers with specified externalId or serial have been found
ERR_VEH_NOT_FOUND the vehicle with the specified externalId or serial was not found
ERR_MULTIPLE_VEH multiple vehicles with specified externalId or serialhave been found
ERR_LOC_NOT_VALID the custom location type without latitude and longitude was found

Get Mobile Events

Retrieve mobile events such as success, on_duty, failed, … for the currently active plan (i.e. the last plan that was sent to drivers).

Each get_events request returns up to 500 events which occurred after the specified tag. The result will contain a new tag which you can use in the next get_events request to skip already received events.

HTTP Request

GET https://api.optimoroute.com/v1/get_events

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Parameters

Property Type / Default Description
after_tag
optional		 string
-		 Specify the after_tag to retrieve only the events which occurred since a specific prior call to get_events.
In this case, the after_tag needs to contain the tag returned in the prior call.
See example below.

Response

Property Type / Default Description
success
mandatory		 boolean
-		 true unless an error occurred.
events
optional		 list of event objects
[]		 A list of events objects in the order they arrived from drivers’ mobile apps.
tag
optional		 string
-		 Tag marks the point of time of the last event received in this response. Use it to specify the after_tag query parameter in the next get_events request.
remainingEvents
optional		 integer
unchanged		 The number of events that occurred but were not fetched in this response (in each response at most 500 events are returned).

Event Object

Property Type Description
event
mandatory		 string Event type. Currently one of the following:
on_duty – the driver went on duty
off_duty – the driver went off duty
start_service - the driver started the service
success – the specified order was completed successfully
failed – the driver failed to complete the order
rejected – the driver rejected the order
start_route – the driver started the route
end_route – the driver ended the route
start_time_changed – the driver changed the planned start time
unixTimestamp
mandatory		 integer The time at which event occurred.
Number of seconds elapsed since 00:00 UTC January 1st 1970.
utcTime
mandatory		 ISO 8601 date (string) The UTC date and time at which the specified event occurred.
localTime
mandatory		 ISO 8601 date (string) The local time on order location at which the specified event occurred.
driverName
optional		 string The driver’s name.
Will be sent for events that are related to a specific driver.
driverSerial
optional		 string The driver’s serial number.
Will not be sent if empty or if the event is not related to a specific driver.
driverExternalId
optional		 string The driver’s external identifier.
Will not be sent if empty or if the event is not related to a specific driver.
orderNo
optional		 string The identifier of the affected order.
Not sent for some events such as on_duty.
orderId
optional		 string
-		 The read-only unique identifier of the affected order, assigned by OptimoRoute.
Not sent for some events such as on_duty.
plannedStartTime
optional		 Time object The time when the driver plans to start the route.
Will be included only with the start_time_changed event.

The returned event fields unixTimestamp, utcTime and localTime all refer to the same moment at which the event occurred, so you can use whichever is more convenient.

Please note that some mobile devices might be offline temporarily and they will sync their events only after they reconnect so the events you’ll receive might arrive out of chronological order. For example, the first driver might successfully complete the order 001 at 9:00 AM, but might be offline until 09:15 AM. The second driver could finish the order 002 at 9:10 AM, but might be online the whole time. The server will receive the event for the order 002 first and only then the event for the order 001.

Examples

In the first request we won’t specify the after_tag parameter (we’ll leave it empty):

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Response:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [
    {
      "unixTimestamp": 1516294800,
      "utcTime": "2018-01-18T17:00:00",
      "localTime": "2018-01-18T09:00:00",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "event": "on_duty",
    },
    {
      "unixTimestamp": 1516296030,
      "event": "success",
      "utcTime": "2018-01-18T17:20:30",
      "localTime": "2018-01-18T09:20:30",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD232",
      "orderId": "f7afe58fcddfcbf9f42620c79ebad7ff"
    }
  ],
  "success": true
}

We’ll retry the query in 10 seconds, but this time we’ll use the tag we received in the last result as our after_tag parameter:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Response:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [],
  "success": true
}

There were no new events in the meantime. We’ll retry the query in 10 seconds:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Response:

{
  "remainingEvents": 0,
  "tag": "qwe9876541213",
  "events": [
    {
      "unixTimestamp": 1516298030,
      "event": "success",
      "utcTime": "2018-01-18T17:53:50",
      "localTime": "2018-01-18T09:53:50",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD771",
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ],
  "success": true
}

Get Order Completion

Retrieve completion details for one or more orders, once they have been completed. For real-time order status updates please use the Get Mobile Events endpoint

HTTP Request

POST https://api.optimoroute.com/v1/get_completion_details

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY'

Parameters

POST Request body example:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "orderNo": "ORD55"
    },
    {
      "orderNo": "XXXYZ"
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
    }
  ]
}
Property Type / Default Description
orders
mandatory		 list of order objects
-		 List of order objects whose completion details will be retrieved. Each order object can contain either of:
  • orderNo: the user-specified identifier of an order
  • id: the unique identifier of the order, assigned by OptimoRoute
At most 500 orders can be specified.



For flexibility, the call to get_completion_details can also be done as a HTTP GET request:

GET request example:

curl 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99&orderNo=ORD55&orderNo=XXXYZ'
Property Type / Default Description
orderNo
mandatory		 string
-		 The user-specified identifier of an order; can be repeated to retrieve completion details for multiple orders

Response

Response:

{
  "orders": [
    {
      "success": true,
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
          "unixTimestamp": 1604267055,
          "utcTime": "2020-11-01T21:44:15",
          "localTime": "2020-11-01T16:44:15"
        },
        "endTime": {
          "unixTimestamp": 1604267305,
          "utcTime": "2020-11-01T21:48:25",
          "localTime": "2020-11-01T16:48:25"
        },
        "form": {
          "note": "Customer was not available, waited for 5 minutes, nobody answered the door"
        },
        "tracking_url": "https://order.is/Ka231Xpp"
      }
    },
    {
      "success": true,
      "orderNo": "ORD99",
      "data": {
        "status": "success",
        "startTime": {
           "unixTimestamp": 1604264327,
           "utcTime": "2020-11-01T20:58:47",
           "localTime": "2020-11-01T15:58:47"
        },
        "endTime": {
           "unixTimestamp": 1604264397,
           "utcTime": "2020-11-01T20:59:57",
           "localTime": "2020-11-01T15:59:57"
        },
        "form": {
          "signature": {
            "type": "image/png",
            "url": "https://optimoroute-vixldutrtzrnkmcpgateah.s3-accelerate.amazonaws.com/1fA-LEwk/yV8921_C5DA/0JCKDRJDSah-4N/fb5f0f06a08243f4aba05430664ddc19.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAI6CIXSXBBNSDQZYN%2F20201101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20201101T185647Z&X-Amz-Signature=6281e5e133e517beb3b041224b87d473122f1626ab371bf1a523dff0ddad642b"
          },
          "barcode": [
            {
              "barcode": "123456",
              "scanInfo": {
                "status": "success",
                "scanned": "123456"
              }
            },
            {
              "barcode": "345678",
              "scanInfo": {
                "images": [
                  {
                    "type": "image/jpeg",
                    "url": "https://..."
                  }
                ],
                "status": "unscannable"
              }
            }
          ],
          "barcode_collections": [
            {
              "barcode": null,
              "scanInfo": {
                "type": "code-128",
                "status": "added",
                "scanned": "000123"
              }
            }
          ]
        }
      }
    },
    {
      "success": true,
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "success": false,
      "orderNo": "XXXYZ",
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND"
    },
    {
      "success": true,
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      "data": {
        "status": "success",
        "startTime": {
          "unixTimestamp": 1661438862,
          "utcTime": "2022-08-25T14:47:42",
          "localTime": "2022-08-25T16:47:42"
        },
        "endTime": {
          "unixTimestamp": 1661438878,
          "utcTime": "2022-08-25T14:47:58",
          "localTime": "2022-08-25T16:47:58"
        },
        "tracking_url": "https://order.is/kzrmzcja"
      }
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if completion details of at least one order were retrieved, false if no orders were retrieved
orders
optional		 list of completion response objects
[]		 A list of objects containing order completion details, one for each requested order.

Completion Response Object

Property Type / Default Description
orderNo
optional		 string
-		 The identifier of the order. Only present if orderNo was used in the request.
id
optional		 string
-		 The unique identifier of the order, assigned by OptimoRoute. Only present if id was used in the request.
success
mandatory		 boolean
-		 true if the operation was successful, false if there was an error.
code
optional		 string
-		 An error code or a warning code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).
data
optional		 object
{}		 Object containing order completion status and metadata. See Completion Details fields for possible keys.

Completion Details fields

The returned Completion Details object will contain fields described below, depending on whether the order has been completed or not, how Proof of Delivery collection is configured, and what has been filled in. The returned Complation Details object may also contain additional fields not yet described here.

Property Type / Default Description
status
mandatory		 string
-		 Order status, see possible values: Order status values
startTime
optional		 Time object
-		 Time when order service was started.
Only present for orders with status servicing, success or failed.
endTime
optional		 Time object
-		 Time when order service was completed (marked with either status success or failed.
Only present for orders with status success or failed.
form
optional		 Form Data object Contains values filled in from the mobile app while completing the order.
Only present if Proof of Delivery is configured.
tracking_url
optional		 string A link to the order's Realtime Order Tracking page. Only present if order has been assigned a tracking number. Tracking number is assigned when plans are sent to driver or the customer notifications have been sent out. Prerequisite is that Order Tracking is enabled.

Order Status Values

Value Description
unscheduled Order has not been scheduled
scheduled Order has not been started yet
on_route Driver is on their way to order location
servicing Order is currently being serviced
success Order was completed successfully
failed Driver failed to complete the order
rejected Order was rejected by the driver
cancelled Order was cancelled by customer

Time object

Property Type Description
unixTimestamp
mandatory		 integer Number of seconds elapsed since 00:00 UTC January 1st 1970.
utcTime
mandatory		 ISO 8601 date (string) The UTC date and time
localTime
mandatory		 ISO 8601 date (string) The local time at the location of order.

The fields unixTimestamp, utcTime and localTime all refer to the same moment, so you can use whichever is more convenient.

Form Data object

All fields in Form Data are optional, and the object may contain additional fields not listed here.

Property Type Description
note
optional		 string The text of the note included when completing the order.
Only present if configured as part of Proof of Delivery and a note has been filled in.
signature
optional		 Image Attachment object The object describes the attached signature image file
Only present if configured as part of Proof of Delivery and a signature has been filled in.
images
optional		 list of Image Attachment objects The object list the attached images
Only present if configured as part of Proof of Delivery and a images have been taken.
barcode
optional		 list of Barcode Scan objects The object describes the attached barcode completion details
Only present if a barcode pre-attached to an order was scanned.
barcode_collections
optional		 list of Barcode Scan objects The object describes the barcodes collected with the order
Only present if configured as a part of Driver App workflow and an unplanned barcode has been scanned during a collection along an order.

Image Attachment object

Property Type Description
type
mandatory		 string The MIME type of the attached image, typically image/png or image/jpeg
url
mandatory		 string The URL at which the image file may be downloaded. The URL will include temporary authentication tokens and will be valid for at least 5 days, but not indefinitely.

Barcode Scan object

Property Type Description
barcode string The barcode attached to the order. May be empty if the barcode is added instead of scanning the pre-atached barcode (e.g. item collection during a delivery)
scanInfo Barcode Info object Object describing barcode scan status and additional information

Barcode Info object

Property Type Description
status
mandatory		 Barcode Status Describes the status of a barcode scan
scanned
optional		 string Barcode that was actually scanned. Might differ from the expected barcode according to the status.
images
optional		 list of Image Attachment objects Images replacing the barcode scanned when the barcode itself is not scannable. May be present with the status unscannable
type
optional		 string The type of the barcode scanned if it could have been inferred at the time of scanning.
Supported types include: code-128, code-39, code-93, codabar, ean-13, ean-8, itf, upc-e, upc-a, qr, pdf-417, aztec, data-matrix

Barcode Status

Status code Description
success the correct barcode was scanned, the value matches the one attached to the order
unscannable the barcode was not scannable. Can have images attached depending on the configuration
added an unplanned barcode was scanned and it's barcode was added
replaced the barcode was replaced at the time of delivery. The scanned property shows the new value
missing the item was not available during the delivery

Error and Warning Codes

In case success is false, data will not be sent and the field code will contain one of the following per-order error codes:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo

Update Order Completion

Update order completion details for one or more orders.

HTTP Request

POST https://api.optimoroute.com/v1/update_completion_details

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_completion_details?key=AUTH_KEY'

Parameters

POST Request body example:

{
  "updates": [
    {
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
           "unixTimestamp": 1604264327,
        },
        "endTime": {
           "unixTimestamp": 1604264397,
        },
      }
    },
    {
      "orderNo": "ORD99",
      "data": {
        "status": "success",
         "startTime": {
          "utcTime": "2020-11-01T21:44:15",
        },
        "endTime": {
          "utcTime": "2020-11-01T21:48:25",
        },
      }
    },
    {
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "orderNo": "ORD56",
      "data": {
        "status": "servicing",
        "startTime": {
           "unixTimestamp": 1692186190,
        },
      }
    },
    {
      "orderNo": "XXXYZ",
      {
        "data": {
          "status": "cancelled"
        }
      }
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      {
          "data": {
            "status": "on_route"
          }
      }
    }
  ],
}
Property Type / Default Description
updates
mandatory		 list of completion details update objects
[]		 A list of order completion details to be updated. At most 500 completion details objects can be specified.

Completion Details Update Object

Property Type / Default Description
orderNo
optional		 string
-		 The identifier of the order. Mandatory if id is not specified.
id
optional		 string
-		 The unique identifier of the order, assigned by OptimoRoute. Mandatory if orderNo was not specified.
data
optional		 object
{}		 Object containing order completion status and metadata. See Completion Details Update fields for possible keys.

Completion Details Update fields

Property Type / Default Description
status
mandatory		 string
-		 Order status, see possible values: Order status values
startTime
optional		 Time update object
-		 Time when order service was started.
Only present for orders with status servicing, success or failed.
endTime
optional		 Time update object
-		 Time when order service was completed (marked with either status success or failed.
Only present for orders with status success or failed.

Time Update Object

Property Type Description
unixTimestamp
optional		 integer Number of seconds elapsed since 00:00 UTC January 1st 1970.
utcTime
optional		 ISO 8601 date (string) The UTC date and time. Ignored if unixTimestamp is specified.
localTime
optional		 ISO 8601 date (string) The local time on order location. Ignored if unixTimestamp or utcTime is specified.

At least one of unixTimestamp, utcTime, localTime should be specified.

Response

Response:

{
  "orders": [
    {
      "success": true,
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
          "unixTimestamp": 1604264327,
          "utcTime": "2020-11-01T20:58:47",
          "localTime": "2020-11-01T15:58:47"
        },
        "endTime": {
          "unixTimestamp": 1604264397,
          "utcTime": "2020-11-01T20:59:57",
          "localTime": "2020-11-01T15:59:57"
        },
      }
    },
    {
      "success": true,
      "orderNo": "ORD99",
      "data": {
        "status": "success",
        "startTime": {
          "unixTimestamp": 1604267055,
          "utcTime": "2020-11-01T21:44:15",
          "localTime": "2020-11-01T16:44:15"
        },
        "endTime": {
          "unixTimestamp": 1604267305,
          "utcTime": "2020-11-01T21:48:25",
          "localTime": "2020-11-01T16:48:25"
        },
      }
    },
    {
      "success": true,
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "success": true,
      "orderNo": "ORD56",
      "data": {
        "status": "servicing",
        "startTime": {
          "unixTimestamp": 1692186190,
          "utcTime": "2023-08-16T11:43:10",
          "localTime": "2023-08-16T06:43:10"
        },
      }
    },
    {
      "success": false,
      "orderNo": "XXXYZ",
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND"
    },
    {
      "success": true,
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      "data": {
        "status": "on_route",
      }
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if completion details of at least one order were updated, false if no order completion details were updated.
updates
optional		 list of completion response objects
[]		 A list of objects containing order completion details, one for each requested update. Completion Response Object

Update Drivers Positions (bulk)

Updates positions of multiple drivers at given timestamps.

HTTP Request

POST https://api.optimoroute.com/v1/update_drivers_positions

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_drivers_positions?key=AUTH_KEY'

Parameters

Request body example:

{
  "updates": [
    {
      "driver": {
        "externalId": "001"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 0,
          "accuracy": 10.1
        },
        {
          "timestamp": 1692186194,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 0,
          "accuracy": 10.1
        }
      ]
    },
    {
      "driver": {
        "serial": "S002"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 20.3,
          "accuracy": 10.1,
          "heading": 34.2
        },
        {
          "timestamp": 1692186194,
          "latitude": 45.805923,
          "longitude": 16.237844,
          "speed": 22.1,
          "accuracy": 12.4,
          "heading": 34.2
        }
      ]
    },
    {
      "driver": {
        "externalId": "S003"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    },
    {
      "driver": {
        "serial": "S004"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    },
    {
      "driver": {
        "serial": "S004"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    }
  ]
}
Property Type / Default Description
updates
mandatory		 list of Driver Positions objects
-		 List of objects each specifying positions for a driver. At most 1 object for a single driver can be specified.

Driver Positions Object

Property Type / Default Description
driver
mandatory		 object
-		 An object with string properties serial or externalId that uniquely identifies the Driver. Example: {"serial": "102"} or {"externalId": "444"}.
positions
mandatory		 list of Position objects
-		 list of positions accross time. At most 100 positions can be specified for a single driver.

Position Object

Property Type / Default Description
timestamp
mandatory		 integer The time at which event occurred.
Number of seconds elapsed since 00:00 UTC January 1st 1970.
latitude
mandatory		 decimal
-		 Position latitude in degrees.
longitude
mandatory		 decimal
-		 Position longitude in degrees.
accuracy
optional		 decimal
-		 Radius of uncertainty for location in meters.
speed
optional		 decimal
-		 Speed in meters per second.
heading
optional		 decimal
-		 Direction of travel in degrees, 0 indicating north, 90 east, 180 south, ...

Response

Response example:

{
  "updates": [
     {
      "success": true,
      "driver": {
        "externalId": "001"
      },
    },
    {
      "success": false,
      "driver": {
        "serial": "S002"
      },
      "code": "ERR_MULTIPLE_DRV",
      "message": "Found multiple drivers with matching external id or serial number.",
    },
    {
      "success": false,
      "driver": {
        "externalId": "S003"
      },
      "code": "ERR_DRIVER_NOT_FOUND",
      "message": "Could not find a driver with the matching id",
    },
    {
      "success": false,
      "driver": {
        "serial": "S004"
      },
      "code": "ERR_MULTIPLE_DRV_POS",
      "message": "Multiple driver positions objects for a single driver",
    }, {
      "success": false,
      "driver": {
        "serial": "S004"
      },
      "code": "ERR_MULTIPLE_DRV_POS",
      "message": "Multiple driver positions objects for a single driver",
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory		 boolean
-		 true if at least one operation was successful, false if all failed
updates
 list of Driver Response Objects
-		 Each Driver Response Objects in the list corresponds to the respective Driver Positions object in the request.

Driver Response Object

Property Type / Default Description
success
mandatory		 boolean
-		 true if the operation succeeded, false if there was an error.
driver
optional		 object
-		 Identifier of the respective driver as an object with string properties serial or externalId.
code
optional		 string
-		 A per-order error code (not set if the operation was successful).
message
optional		 string
-		 An error description or a warning description (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Update Drivers Positions method:

Error Code Description
ERR_DRIVER_NOT_FOUND the driver with the specified externalId or serial was not found
ERR_MULTIPLE_DRV multiple drivers with specified externalId or serial have been found
ERR_MULTIPLE_DRV_POS multiple drivers positions objects specified for a single driver

Search Orders

Retrieves one or more orders from the system.

HTTP Request

POST https://api.optimoroute.com/v1/search_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/search_orders?key=AUTH_KEY'

Parameters

Request body examples:

{
  "dateRange": {
    "from": "2022-01-01",
    "to": "2022-01-03",
  },
  "includeOrderData": true,
  "orderStatus": ["failed", "rejected"]
}

{
  "orders": [
    {
      "orderNo": "10203"
    },
    {
      "orderNo": "10204"
    }
  ]
}

{
  "orders": [
    {
      "id": "72b85bf77fe53ebdc689c42ddaacad73"
    },
    {
      "id": "5a9247a50481860d44573f7d7f8799d5"
    }
  ],
  "includeScheduleInformation": true
}
Property Type / Default Description
orders list of order objects
-		 List of order objects to retrieve. Each order object can contain either of:
  • orderNo: the user-specified identifier of an order
  • id: the unique identifier of the order, assigned by OptimoRoute
At most 500 orders can be specified.
dateRange daterange object An object with from and to fields, for example:
{"from": "2022-01-01", "to": "2022-01-03"}. The range can span at most 35 days, i.e. 5 weeks.
orderStatus
optional		 list of strings
-		 List of order status strings, to optionally filter the retrieved orders by status.
See possible values: Order status values.
includeOrderData
optional		 boolean
false		 Set this to true if you need to fetch the order data for the orders found
includeScheduleInformation
optional		 boolean
false		 Set this to true if you need to fetch the order scheduling information
after_tag
optional		 string
-		 Specify the after_tag to retrieve only the next page of results from a previous call to this endpoint.
In this case, all the parameters need to be repeated with same values as the previous call, and the after_tag needs to contain the value returned in the prior call.

At least one of orders or dateRange properties must be specified in the request.

Response

Response example with includeOrderData

{
  "success": true,
  "orders": [
    {
      "id": "cd013f61ad8155802ad4321f2b411f4f",
      "data": {
        "orderNo": "10205",
        "date": "2022-01-03",
        "type": "T",
        "priority": "M",
        "duration": 75,
        "notes": "",
        "email": "",
        "phone": "",
        "load1": 0,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "customField1": "Revision 5",
        "customField2": "184.5",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "id": "cd013f61ad8155802ad4321f2b411f4f",
        "assignedTo": null,
        "location": {
          "locationNo": "T1275",
          "locationName": "T1275",
          "address": "Moneta, VA 24121, United States",
          "latitude": 37.2636426,
          "longitude": -79.6105659,
          "notes": "",
          "valid": true,
          "checkInTime": 0
        },
        "skills": ["VA"],
        "vehicleFeatures": [],
        "timeWindows": [],
        "notificationPreference": "dont_notify",
        "allowedWeekdays": ["mon", "tue", "wed", "thu"],
        "allowedDates": {}
      }
    }
  ]
}

Response example with includeScheduleInformation; presence of after_tag after only 2 results exaggerated for illustration only.

{
  "success": true,
  "orders": [
    {
      "id": "72b85bf77fe53ebdc689c42ddaacad73",
      "scheduleInformation": {
        "driverExternalId": "",
        "driverSerial": "JQP",
        "driverName": "John Q P",
        "vehicleRegistration": null,
        "vehicleLabel": null,
        "stopNumber": 3,
        "scheduledAt": "10:03",
        "scheduledAtDt": "2022-01-02 10:03:44",
        "arrivalTimeDt": "2022-01-02 10:03:44",
        "travelTime": 2033,
        "distance": 32254
      }
    },
    {
      "id": "5a9247a50481860d44573f7d7f8799d5",
      "scheduleInformation": null
    },
  ],
  "after_tag": "gAAAAABjGMzYTPcM2QlRwp69tNXXU7asLhGUXJ0SfZZfieAbi37z73cmyfhaoSHWiT8sJX2HnvLjvDTrK3l9TySz0vfWEkuzx6OYOkS4Qc37smFa2Q0t7WE="
}
Property Type / Default Description
success
mandatory		 boolean
-		 This will be false if there was an error and no orders were retrieved
orders
mandatory		 list of order response objects
-		 Each object in the list represents one result order found in the system. See Order Response Object section for more information.
Up to 500 orders will be returned in one call. Use after_tag to fetch the remaining pages.
after_tag
optional		 string
-		 Only present if the there are more pages of results to fetch. To fetch the next page of results, repeat the call to this endpoint and with the after_tag parameter and all other parameters with same values.

Order Response Object

Property Type / Default Description
id
mandatory		 string
-		 The unique identifier of the order, assigned by OptimoRoute.
data
optional		 Order object
-		 The retrieved order data; only present if includeOrderData was set to true
scheduleInformation
optional		 schedule info object
-		 The order scheduling information; only present if includeScheduleInformation was set to true. This will be null if the order is not scheduled.
shell