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:

the whole request can fail (e.g. a serious validation or programming error). The response will contain an error code.
the operation failed for some orders, but succeeded for others. The response will contain a list in which some objects have an error code.

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": "",
  "customFields": {
    "fruit_type": "apple",
    "quantity": 100,
    "purity": 99.99,
    "instructions": "Deliver to the customer's door."
  },
  "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. If not specified, newly created orders will use the default value configured in OptimoRoute.
`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`.
`load3`	decimal	See `load1`.
`load4`	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. NOTE: `customField1` through `customField5` are legacy custom fields that do not support different types and are limited to five fields. Learn more about the new custom fields or contact OptimoRoute support to activate them.
`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.
`customFields`	custom fields object	An object containing custom fields. See CustomFields Object.
`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:

"location": {
  "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	Minimum waiting time at the location (in minutes). If not specified, newly created locations will use the default value configured in OptimoRoute (zero by default). 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.

CustomFields Object

The CustomFields Object can contain any number of properties, where each property name matches the key of a custom field configured in OptimoRoute.

CustomFields Object example (fruit_type is of type Single Select where apple is an option key, quantity is of type Number with 0 decimal places, purity is of type Number with 2 decimal places and instructions is of type Text):

"customFields": {
  "fruit_type": "apple",
  "quantity": 100,
  "purity": 99.99,
  "instructions": "Deliver to the customer's door."
}

Property	Type	Description
`{custom_field_key}`	string or decimal or boolean	If the custom field is configured with type `Text` or `Number`, the provided value will be converted to the appropriate type if possible. If the custom field is configured with type `Single Select`, the value must exactly match one of the option keys configured for that field.

NOTE: Learn more about the new custom fields or contact OptimoRoute support to activate them. Legacy custom fields (custom fields with keys custom_field_1 through custom_field_5) should not be included in this object - these are set using the separate fields in the Order Object (customField1 through customField5).

Position Object

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

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, 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:

locationNo
The location number of a location already existing in the system. An existing location is used.
NOTE: the address, latitude + longitude and locationName should NOT be specified, otherwise the system will try to geocode the location again or create one with a defined GPS location.
latitude + longitude + locationName (with optional address and locationNo)
The location is defined by the latitude and longitude.
The location name will be set to the value of locationName field.
The location address will be set to address if address is set, otherwise it will be left blank.
The location number will be set to locationNo if locationNo is set, otherwise it will be left blank.
address (with optional locationName and locationNo)
The system will try to find an existing locations with the specified address (and locationName if one is specified). If an existing location is not found the location address will be geocoded based on the supplied address.
The location name will be set to locationName field if locationName is supplied, otherwise it will be set to the value of address field.
The location number will be set to locationNo if locationNo is set, otherwise it will be left blank.

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:

if id is given, the existing order will be updated with the provided values;
- properties that are not provided in the request will keep their existing values
if id is not given, and orderNo is not given or no order is found, a new order will be created;
- properties date and location are mandatory
- properties duration and type will use the default values configured in OptimoRoute
- other properties can be omitted, in which case the default values listed in Order object will be used
if id is not given, and an existing order with matching orderNo is found, the existing order will be updated with the provided values;
- properties that are not provided in the request will keep their existing values

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.
`forceDelete` optional	boolean `false`	If `true`, usual restrictions regarding deleting orders on a live plan are ignored.

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.
`forceDelete` optional	boolean `false`	If `true`, usual restrictions regarding deleting orders on a live plan are ignored.

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.
`includeRouteStartEnd` optional	boolean `false`	Optional property to include the route’s start and end locations in the output.

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:

Enable/disable driver
Driver work time from
Driver work time to
Assigned vehicle
Vehicle load capacity #1
Vehicle load capacity #2
Vehicle load capacity #3
Vehicle load capacity #4
Driver start location
Driver end location

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:

Enable/disable driver
Driver work time from
Driver work time to
Driver start location
Driver end location
Assigned vehicle
Vehicle load capacity #1
Vehicle load capacity #2
Vehicle load capacity #3
Vehicle load capacity #4

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 serial`have 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.
`position` optional	Position object	Geographical position where the event ocurred. In this object `timestamp`, `latitude` and `longitude` will always be present, with an additional `distanceToLocation` decimal number of meters away from the affected order's location. Only sent for events related to orders, where the driver was expected to be at the location.

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",
      "position": {
        "timestamp": 1516298028,
        "latitude": 41.79078,
        "longitude": -71.42226,
        "accuracy": 4.0,
        "distanceToLocation": 31.3
      }
    }
  ],
  "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"
        },
        "startPosition": {
          "timestamp": 1661438860,
          "latitude": 41.70141,
          "longitude": -71.4531,
          "accuracy": 14.0,
          "distanceToLocation": 12.5
        },
        "endTime": {
          "unixTimestamp": 1661438878,
          "utcTime": "2022-08-25T14:47:58",
          "localTime": "2022-08-25T16:47:58"
        },
        "endPosition": {
          "timestamp": 1661438878,
          "latitude": 41.70139,
          "longitude": -71.4533,
          "accuracy": 8.0,
          "distanceToLocation": 23.1
        },
        "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`.
`startPosition` optional	Position object -	Geographical position where order service was started, with `timestamp`, `latitude` and `longitude` always present. Additionally contains `distanceToLocation` decimal representing the number of meters away from the affected order location. 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`.
`endPosition` optional	Position object -	Geographical position where order service was completed, with `timestamp`, `latitude` and `longitude` always present. Additionally contains `distanceToLocation` decimal representing the number of meters away from the affected order location. 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

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. In each object, `timestamp`, `latitude` and `longitude` are mandatory.

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.