NAV Navbar
Logo
http+json shell

Introduction

WorkWave Route Manager (WWRM) exposes its data via an Application Programming Interface (API). This document is the official reference for that functionality.

To start experimenting with a few examples we recommend a REST client called Postman. Simply tap the button below to import a pre-made collection of examples and the associated environment variables.

See the chapter about Postman on how to install and setup the collection.

Basic concepts

Assumptions

Throughout this document it is assumed that the reader is well acquainted with the WorkWave Route Manager Web Application, its features and terminology.

The API is entirely HTTP-based

Methods to retrieve data from the API require a GET request. Methods that submit or change data require a POST. Methods that destroy data require a DELETE. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one. HTTP Response Codes are meaningful.

The API is a RESTful resource

The API attempts to conform to the design principles of Representational State Transfer (REST). More details on REST can be found here. Libraries to build REST-compatible API clients are readily available for several programming languages. A list of REST frameworks is available at the bottom of the above mentioned page.

The format used for structured data exchange is JSON

The API supports the JSON (JavaScript Object Notation) format. Details on how JSON works can be found here and here. Libraries that convert to and from the JSON format are readily available for popular and less popular programming languages. A full index, sorted by language, can be found at the bottom of this page

The API works with both plain HTTP and HTTP-within-SSL/TLS (HTTPS). HTTPS is highly recommended to avoid passing both the authentication KEY and potentially confidential data (e.g.: clients’ names and addresses) in clear text over the web.

Parameters have certain expectations

Some API methods take optional or requisite parameters. Please keep in mind that all query-string parameter values should be converted to UTF-8 and URL encoded.

Numeric data type limitations

In addition to formal validations reported for each specific method, there are also restrictions on the maximum and the minimum values allowed for the parameters due to their data type.

In particular:

Using a value outside the allowed range will return an error on the whole request.

Authentication

Authentication is performed using an API key provided by WorkWave. The API key must be included in the HTTP(S) request using one of the following two methods:

Where both are provided the query-string parameter takes precedence.

The API key is a string, more specifically it is a UUID in its canonical form (e.g.: “123e4567-e89b-12d3-a456-426655440000”).

Asynchronous requests

All requests that add, update or delete data (write-requests) are asynchronous.

All asynchronous requests return immediately with a requestId. The actual response, complete with the requestId, is POSTed to the notifications callback URL as soon as the originating request is processed (see the following paragraph for more details about notifications).

Notifications

The WorkWave Route Manager API supports a notification mechanism based on HTTP callbacks (aka web-hooks).

A callback URL is defined on a per-account basis to receive event notifications. Notification messages are POSTed to the callback URL.

Notifications include:

Queueing and Throttling

All asynchronous API requests are queued on a per-territory basis and processed one by one in the order they have been queued (FIFO).

The queue has a maximum size of 10 items. Attempting to queue more than this number of requests will return a 429 “Too Many Requests” error.

Throttling and rate-limiting schemes are applied on a per-territory and per-request-type basis to both synchronous and asynchronous requests to prevent overloading the system with too many / too fast requests.

HTTP Response Codes and Errors

HTTP Status Codes

The WorkWave Route Manager API attempts to return appropriate HTTP status codes for every request.

Error Messages

{
  "errorCode": 600,
  "errorMessage": "Adding 75 Orders to the existing 980 exceeds the maximum of 1000 allowed for operations on territory [New York]"
}

When the WorkWave Route Manager API returns error messages, it does so in JSON format. See examples in the right panel.

Error Codes

Error codes, as found in the body of returned error messages, further define the scope of an error. The following error codes may be returned:

Operations and Simulations

In RouteManager, each Territory stores its data in a structure called a Route Plan. By default, creating a Territory generates an Operations Route Plan, which manages all information related to orders, vehicles, drivers, routes, execution, and more. Only one Operations Route Plan can exist in each Territory; deleting and re-creating the Operations Route Plan connected with a Territory is not possible.

Simulations

Through the user interface (UI), you can create copies of the Operations Route Plan known as Simulations. Each Territory can have multiple Simulations, with each Simulation identified by a unique ID (in UUID format) and a name.

Key Differences Between Operations and Simulations:

Simulation REST APIs

A set of REST APIs is available to interact with Simulations. These APIs allow you to:

Core API sets and use cases

WorkWave Route Manager offers four different API sets, where each set is dedicated to specific use cases.

Orders API set

Allows for CRUD operations on Orders.

Its main purpose is to allow automated synchronization of Order data between WorkWave Route Manager and ERP Systems.

Asynchronous notifications are POSTed to the callback URL whenever an Order is updated, either as a consequence of our direct actions or by some other actor (other API user or human user logged into the Web Application).

Notifications are about changes to “static”, Order-definition data (e.g.: address, service time, time window, loads) and do not include updates about “live” data such as ETAs and Execution Events (e.g.: time-in, time-out) received from Mobile Applications; that is the purpose of the TimeOfArrival API.

Time Of Arrival API set

Allows updating and retrieval of live routes data, including updated time of arrival information. Enables use cases such as:

Approved Plans API set

Allows retrieval of approved route plan data as well as approving, and revoking approval of, Routes on a per-date or per-route basis.

Asynchronous notifications are POSTed to the callback URL whenever routes planned for a date are marked or unmarked as “approved”.

Enables use cases such as:

Scheduling API set

Provide means to assign and unassign Orders to/from Routes exposing functionality like full plan (re)optimization, fitting-in unassigned Orders and explicitly unassigning Orders from their current Routes.

Asynchronous notifications are POSTed to the callback URL whenever a scheduling event completes.

Enables use cases such as:

GPS Tracking API set

Allows retrieval of GPS tracking data like current and historical [planned] data like position, heading, speed, etc

Enables use cases such as:

Proposals API set

The Proposals API set allows for obtaining real-time information as to where a new Order could be inserted into existing planned routes or empty routes. Its main characteristic is that it accepts multiple time slots to be investigated in parallel.

The returned result is a set of “proposals”, one per slot, with a preview of the Route in case the Order fits into the slot.

If one of the proposals is accepted the Order is added to the plan, already assigned to the proposed Route.

Enables use cases such as:

Helper API sets

In addition to the core API sets, the following additional helper REST resources are available:

Versioning and evolution

Route Manager API is constantly evolving. Existing methods are being improved and extended and new functionalities are being added.

Backward-compatible changes are implemented as extensions to existing versions, while backward-incompatible changes are implemented by introducing entirely new versions.

While we are strongly committed to never introduce breaking changes to existing versions, integration code must be flexible enough to handle backward-compatible updates gracefully.

Here is a list of backward-compatible changes together with how integration code is supposed to deal with them.

Introducing a new REST resource

This is never a problem as existing integration code, not knowing about new endpoints, will not use them.

Adding properties to existing response objects

Existing integration code should ignore unmapped fields.

Note: Some JSON libraries, most notably Jackson, by default will throw an error in case an unmapped field is encountered during parsing. It is important that such libraries are configured to ignore (and possibly report) unmapped fields rather than fail.

Adding optional properties to existing request objects

This is never a problem as existing integration code, not knowing about the new fields, will not populate them.

Adding new asynchronous notification events

Existing integration code must ignore any unexpected asynchronous notification objects (it is still recommended to log these events to keep track of them).

Adding new values to existing enums in request objects

This is never a problem as existing integration code, not knowing about the new values, will not use them.

Adding new values to existing enums in response objects

This is trickier and we try to limit it only to cases where the change can be handled in a backward-compatible way.

An example would be adding a new value to ExecutionEvent‘s type property. Existing integration code should ignore ExecutionEvents with an unknown type (it is still recommended to log these events to keep track of them).

Postman

Postman is a handy API client that facilitates testing and experimenting with RESTful endpoints.

Installing Postman

Before you can use the Route Manager API Postman Collection, you must either download the Postman App for Windows, OS X, or Linux or you can use Postman online:

Install the API Collection

We’ve created a Postman Collection that contains all the Route Manager API RESTful endpoints, including some examples. Click the Run in Postman button below to get started.

Environment Variables

In order to use the above Postman collection, you will need to set some environment variables in Postman. After importing it, select wwrm-template from the list of environments and populate the following:

Callback API

Get Callback URL

curl https://wwrm.workwave.com/api/v1/callback?key=AUTH_KEY

GET /api/v1/callback HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "url": "https://my.server.com/callback"
}

Returns the callback URL (synchronous).

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/callback

THROTTLING

Leaky bucket (size:5, refill: 1 per 5 minutes)

RETURN VALUES

Property Type Description
url String The callback URL

Set Callback URL

curl -H "Content-Type: application/json" -X POST -d '{"url":"https://my.server.com/new-callback", "test": true}' https://wwrm.workwave.com/api/v1/callback?key=AUTH_KEY

POST /api/v1/callback HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "url": "https://my.server.com/new-callback",
  "signaturePassword": "g394g732vhsdfiv34",
  "test": true
}

The above command returns JSON structured like this:

{
  "url": "https://my.server.com/new-callback",
  "previousUrl": "https://my.server.com/callback"
}

And in case the test fails:

{
  "errorCode": 2000,
  "errorMessage": "Server at URL [https://my.server.com/callback] failed to respond to the test message. Expected HTTP code [200], received [404]"
}

The POSTed test message looks something like this:

POST /new-callback?reqId=test HTTP/1.0
Host: my.server.com
Accept-Encoding: gzip,deflate
Connection: close
Content-Length: 96
Content-Type: application/json; charset=UTF-8
User-Agent: WorkWaveRouteManager-WebHook/1.0

{
    "requestId": "test",
    "territoryId": "test",
    "event": "test",
    "data": "test"
}

HMAC computation pseudocode. See also examples in other languages

var message = "https://my.server.com/new-callback?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93";
var secret = "g394g732vhsdfiv34";
var hash = CryptoJS.HmacSHA256(message, secret);
var signature = hash.toString(CryptoJS.enc.Base64); // ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa+U=

HMAC verification pseudocode

var inboundRequestUrl = "https://my.server.com/new-callback?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93&signature=ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa%2BU%3D"
var signatureFromUrl = new URL(inboundRequestUrl).getQueryStringParameter("signature");
// strip the "signature" parameter from the URL without otherwise altering either the content or the sequence of the other URL parameters
var inboundRequestUrlWithoutSignature = "https://my.server.com/new-callback?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93";
var secret = "g394g732vhsdfiv34";
var hash = CryptoJS.HmacSHA256(inboundRequestUrlWithoutSignature, secret);
var computedSignature = hash.toString(CryptoJS.enc.Base64);
var isUrlOk = computedSignature == signatureFromUrl;

Sets the callback URL (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per 5 minutes)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/callback

REQUEST BODY

Property Type Description
url String The callback URL
signaturePassword String Optional, defaults to null. If set, both a nonce and a signature parameter are added to the querystring of each POSTed callback. signature is set to the base64 hash computed using HMAC-SHA256 where message is the full URL w/ querystring and secret is signaturePassword. See also the pseudocode in the right panel. This allows the request to be authenticated and to confirm that it is coming from WorkWave Route Manager servers.
test boolean Optional, defaults to false. If true a test callback message is synchronously POSTed to the remote server. url is only set if the response is a 200 OK, otherwise a 400 BAD REQUEST error is returned with a message detailing the failure reason
headers map[String]String Optional, defaults to null. If set the headers are added to each POSTed callback. The concatenated string of all the keys and all the values cannot be longer than 256k characters.

RETURN VALUES

Property Type Description
previousUrl String The previous callback URL
url String The current callback URL

Delete Callback URL

curl -X DELETE https://wwrm.workwave.com/api/v1/callback?key=AUTH_KEY

DELETE /api/v1/callback HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "url": null,
  "previousUrl": "https://my.server.com/callback"
}

Deletes the callback URL and the accompanying signaturePassword, if set, disabling all notifications (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per 5 minutes)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/callback

RETURN VALUES

Property Type Description
previousUrl String The previous callback URL
url String The current callback URL (null in this case)

Validation API

Validate Contact Info

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/validation/contacts?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/validation/contacts HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "emailAddresses": ["test@example.com", "test@example."],
  "phoneNumbers": ["+18007620301", "+83244"],
  "allowBlank": true
}

The above command returns JSON structured like this:

{
  "email": {
    "test@example.com": true,
    "test@example.": false
  },
  "phone": {
    "+18007620301": true,
    "+83244": false
  }
}

Validate (formally) a list of email addresses and a list of phone numbers. Phone numbers validation could depend on territory.

THROTTLING

Leaky bucket (size:10, refill: 1 per 3 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/validation/contacts

REQUEST BODY

Property Type Description
phoneNumbers list of String List of phone numbers to be validated
emailAddresses list of String List of email addresses to be validated
allowBlank boolean Optional, defaults to true. If true, blank strings (email addresses and phone numbers) are formally validated as correct; false otherwise

RETURN VALUES (synchronous)

Property Type Description
email map[String][boolean] For each email address within the request, a record is reported within the map: the key is the email addresses, while the value is true in case the address is valid, false otherwise
phone map[String][boolean] For each phone number within the request, a record is reported within the map: the key is the phone number, while the value is true in case the number is valid, false otherwise

Companies API

Add Company

curl -X POST https://wwrm.workwave.com/api/v1/companies?key=AUTH_KEY

POST /api/v1/companies HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "ACME Corp",
  "enabled": true
}

The above command returns JSON structured like this:

{
  "requestId": "602b663a-67e1-4cfb-bdb0-d19fed149c1d"
}

And triggers an CompaniesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "602b663a-67e1-4cfb-bdb0-d19fed149c1d",
  "event": "companiesChanged",
  "data": {
    "created": [
      "0c920b8e-e904-444c-8371-63cd62f5b1bb",
    ],
    "updated": [],
    "deleted": []
  }
}

Add a new Company.

THROTTLING

Leaky bucket (size:5, refill: 1 per 10 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/companies

REQUEST BODY

Property Type Description
name String Name of the new company, must be unique
enabled boolean True to let the company be assigned to orders/users (it can be assigned to users only using UI), false otherwise

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
event String Set to companiesChanged
data CompaniesChanged OR ErrorResponse

List Companies

curl https://wwrm.workwave.com/api/v1/companies?key=AUTH_KEY

GET /api/v1/companies HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
    "companies": {
        "0c920b8e-e904-444c-8371-63cd62f5b1bb": {
            "id": "0c920b8e-e904-444c-8371-63cd62f5b1bb",
            "name": "ACME Corp",
            "enabled": true
        }
    }
}

List all the available Companies (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per 10 seconds)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/companies

RETURN VALUES

Property Type Description
companies map[UUID]Company A map where the key is the companyId and the value is the associated Company object

Replace Company

curl -X PUT https://wwrm.workwave.com/api/v1/companies/0c920b8e-e904-444c-8371-63cd62f5b1bb?key=AUTH_KEY

PUT /api/v1/companies/0c920b8e-e904-444c-8371-63cd62f5b1bb HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "ACME Corp",
  "enabled": true
}

The above command returns JSON structured like this:

{
  "requestId": "d04eeeab-8d4b-4b53-8acc-2a3072fb596c"
}

And triggers an CompaniesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "d04eeeab-8d4b-4b53-8acc-2a3072fb596c",
  "event": "companiesChanged",
  "data": {
    "created": [],
    "updated": [
        "0c920b8e-e904-444c-8371-63cd62f5b1bb"
    ],
    "deleted": []
  }
}

Replace an existing Company.

THROTTLING

Leaky bucket (size:5, refill: 1 per 10 seconds)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/companies/:companyId

REQUEST BODY

Property Type Description
name String Name of the updated company, must be unique
enabled boolean True to let the company be assigned to orders/users (it can be assigned to users only using UI), false otherwise

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
event String Set to companiesChanged
data CompaniesChanged OR ErrorResponse

Delete Company

curl -X DELETE https://wwrm.workwave.com/api/v1/companies/0c920b8e-e904-444c-8371-63cd62f5b1bb?key=AUTH_KEY

DELETE /api/v1/companies/0c920b8e-e904-444c-8371-63cd62f5b1bb HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "d93fe828-d1cc-4afc-ac58-c5938b45fe9d"
}

And triggers an CompaniesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "d93fe828-d1cc-4afc-ac58-c5938b45fe9d",
  "event": "companiesChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
        "0c920b8e-e904-444c-8371-63cd62f5b1bb"
    ]
  }
}

Delete an existing Company.

THROTTLING

Leaky bucket (size:5, refill: 1 per 10 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/companies/:companyId

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
event String Set to companiesChanged
data CompaniesChanged OR ErrorResponse

Territories API

List Territories

curl https://wwrm.workwave.com/api/v1/territories?key=AUTH_KEY

GET /api/v1/territories HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "territories": {
    "429defc8-5b05-4c3e-920d-0bb911a61345": {
      "id": "429defc8-5b05-4c3e-920d-0bb911a61345",
      "name": "API DEMO",
      "center": [
        33831218,
        -87277506
      ],
      "timeZoneCode": "America/New_York",
      "languageCode": "en",
      "statusReasons": [],
      "borderRestrictionCountryCode": null
    }
  }
}

List all available Territories (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per 5 minutes)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories

RETURN VALUES

Property Type Description
territories map[UUID]Territory A map where the key is the territoryId and the value is the associated Territory object

Edit Territory

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "reasons": ["Absent recipient"]
}

The above command returns JSON structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055"
}

And triggers a TerritoryChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "territoryChanged",
  "data": {
    "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345"
  }
}

Update some preferences for the Territory.

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId

REQUEST BODY

Property Type Description
statusReasons list of String List (full replace) of the allowed reasons (also used by the mobile application) to provide more details about a not completed (with the related status set to reschedule) step. Each reason cannot be longer than 30 characters. The default limit of the number of reasons that can be set is 20.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to territoryChanged
data TerritoryChanged OR ErrorResponse

Simulations API

List Simulations

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulations?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulations HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
    "ccb66278-c870-41ea-9741-f3f1159b10b8": "Simulation - copy 20230401",
    "12c0183b-8ee3-4094-a888-6657a0f4d510": "Simulation - Order bulk",
    "63b22ce5-1ee1-46bb-a831-051546ee578f": "Test"
}

List all available Simulation for the selected territory (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 minutes)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulations

RETURN VALUES

Property Type Description
territories map[UUID][String] A map where the key is the simulationId and the value is the Simulation name

Depots API

List Depots

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "Depot A",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  }
}

List all available Depots (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/depots

RETURN VALUES

Property Type Description
depots map[UUID]Depot A map where the key is the depotId and the value is the associated Depot object

Add Depots

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "regions": [
    {
      "name": "New Depot 1",
      "location": {
        "address": "532 23rd St, Union City, NJ 07087, Stati Uniti",
        "geoAddress": "532 23rd St, Union City, NJ 07087, Stati Uniti",
        "status": "OK",
        "source": "G_GEO",
        "latLng": [
          40767560,
          -74034123
        ],
        "rooftopLatLng": [
          40767543,
          -74034134
        ]
      },
      "setupCost": 1000,
      "setupTimeSec": 3600,
      "color": "CC0077"
    },
    {
      "name": "New Depot 2",
      "location": {
        "address": "106 Beadel St, Brooklyn, NY 11222, Stati Uniti",
        "geoAddress": "106 Beadel St, Brooklyn, NY 11222, Stati Uniti",
        "status": "OK",
        "source": "G_GEO",
        "latLng": [
          40721848,
          -73936771
        ],
        "rooftopLatLng": [
          40721829,
          -73936845
        ]
      },
      "setupCost": 2500,
      "setupTimeSec": 1800,
      "color": "0000CC"
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "871bc65d-b3c6-4c53-875c-512a01175f15"
}

And triggers an DepotsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "871bc65d-b3c6-4c53-875c-512a01175f15",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [
      "f93ab100-64bc-4eaa-b9b4-14a9e2041cad",
      "ec6f04a1-6d14-4877-a1a6-f731d20ba35e"
    ],
    "updated": [],
    "deleted": []
  }
}

Add one or more new Depot(s) (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/depots

REQUEST BODY

Property Type Description
depots list of DepotInput A list contiaining the depot to update.

The system will assign a UUID to the Depot and return it in the depotsChanged notification message in the created list.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to depotsChanged
data DepotsChanged OR ErrorResponse

Update Depots

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
 "depots": [
        {
            "id":"f93ab100-64bc-4eaa-b9b4-14a9e2041cad",
            "name": "New Depot Name",
            "color": "FF0000"
        },
        {
            "id":"ec6f04a1-6d14-4877-a1a6-f731d20ba35e",
            "name": "Depot example",
            "color": "99CC10"
        }
    ]
}

The above command returns JSON structured like this:

{
  "requestId": "cbd05050-3b15-4e13-91ac-1bb525dd08ea"
}

And triggers a DepotsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cbd05050-3b15-4e13-91ac-1bb525dd08ea",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [],
    "updated": [
      "f93ab100-64bc-4eaa-b9b4-14a9e2041cad",
      "ec6f04a1-6d14-4877-a1a6-f731d20ba35e"
    ],
    "deleted": []
  }
}

Update one or more Depots (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/depots

REQUEST BODY

Property Type Description
depots list of DepotUpdate A list contiaining the infromation to update.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to depotsChanged
data DepotsChanged OR ErrorResponse

Delete Depots

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/depots HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "depotIds": [
    "f93ab100-64bc-4eaa-b9b4-14a9e2041cad",
    "ec6f04a1-6d14-4877-a1a6-f731d20ba35e"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "6944b64c-9ad6-4d45-b192-7f5fa45b5f03"
}

And triggers an DepotsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "6944b64c-9ad6-4d45-b192-7f5fa45b5f03",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "f93ab100-64bc-4eaa-b9b4-14a9e2041cad",
      "ec6f04a1-6d14-4877-a1a6-f731d20ba35e"
      ]
  }
}

Delete one or more Depot(s) (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/depots

REQUEST BODY

Property Type Description
depotIds list of String List of depotIds to delete

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to depotsChanged
data DepotsChanged OR ErrorResponse

Regions API

List Regions

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "regions": {
    "ddcbe348-5b4d-483d-9d6c-1b149120ca7e": {
      "id": "ddcbe348-5b4d-483d-9d6c-1b149120ca7e",
      "name": "South Jasper",
      "color": "2E5984",
      "poly": [
        [33840336, -87319165],
        [33839766, -87220803],
        [33794127, -87229386],
        [33792558, -87245007],
        [33812528, -87259598],
        [33812956, -87305947],
        [33812956, -87325860]
      ],
      "enterCost": 2000,
      "enterTimeSec": 1200
    }
  }
}

List all available Regions (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/regions

RETURN VALUES

Property Type Description
regions map[UUID]Region A map where the key is the regionId and the value is the associated Region object

Add Regions

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "regions": [
    {
      "name": "South Jasper",
      "color": "2E5984",
      "poly": [
        [33840336, -87319165],
        [33839766, -87220803],
        [33794127, -87229386],
        [33792558, -87245007],
        [33812528, -87259598],
        [33812956, -87305947],
        [33812956, -87325860]
      ],
      "enterCost": 2000,
      "enterTimeSec": 1200
    },
    {
      "name": "Manhattan",
      "color": "0D8800",
      "enterCost": 2500,
      "enterTimeSec": 1800,
      "poly": [
        [40850260, -73944892],
        [40758003, -74002913],
        [40703369, -74015273],
        [40711697, -73976134],
        [40800119, -73929442]
      ]
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "9ba1499d-0055-48b3-9207-53b3ad947866"
}

And triggers an RegionsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9ba1499d-0055-48b3-9207-53b3ad947866",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "regionsChanged",
  "data": {
    "created": [
      "933c5158-517e-4234-a987-46c931914ac4",
      "fe0b11a0-a822-4ced-a374-4ca3a2e352bb"
    ],
    "updated": [],
    "deleted": []
  }
}

Add one or more new Region(s) (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/regions

REQUEST BODY

Property Type Description
regions list of RegionInput object List of the new regions to create

The system will assign a UUID to the Region and return it in the regionsChanged notification message in the created list.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to regionsChanged
data RegionsChanged OR ErrorResponse

Replace Regions

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "regions": [
    {
      "id" : "933c5158-517e-4234-a987-46c931914ac4",
      "name": "South Jasper",
      "color": "11FFCC",
      "poly": [
        [33840336, -87319165],
        [33839766, -87220803],
        [33794127, -87229386],
        [33792558, -87245007],
        [33812528, -87259598],
        [33812956, -87305947],
        [33812956, -87325860]
      ],
      "enterCost": 2000,
      "enterTimeSec": 1200
    },
    {
      "id" : "fe0b11a0-a822-4ced-a374-4ca3a2e352bb",
      "name": "Manhattan",
      "color": "FF0000",
      "enterCost": 2500,
      "enterTimeSec": 1800,
      "poly": [
        [40850260, -73944892],
        [40758003, -74002913],
        [40703369, -74015273],
        [40711697, -73976134],
        [40800119, -73929442]
      ]
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "f65d5fd5-820a-404c-bc21-a1755b25988f"
}

And triggers an RegionsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "f65d5fd5-820a-404c-bc21-a1755b25988f",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "regionsChanged",
  "data": {
    "created": [],
    "updated": [
      "933c5158-517e-4234-a987-46c931914ac4",
      "fe0b11a0-a822-4ced-a374-4ca3a2e352bb"
      ],
    "deleted": []
  }
}

Overwrite one or more Region(s) with new data (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/regions

REQUEST BODY

Property Type Description
regions list of Region object List of regions to replace

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to regionsChanged
data RegionsChanged OR ErrorResponse

Delete Regions

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/regions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "regionIds": [
    "933c5158-517e-4234-a987-46c931914ac4",
    "fe0b11a0-a822-4ced-a374-4ca3a2e352bb"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "9ba1499d-0055-48b3-9207-53b3ad947866"
}

And triggers an RegionsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9ba1499d-0055-48b3-9207-53b3ad947866",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "regionsChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "933c5158-517e-4234-a987-46c931914ac4",
      "fe0b11a0-a822-4ced-a374-4ca3a2e352bb"
      ]
  }
}

Delete one or more Region(s) (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/regions

REQUEST BODY

Property Type Description
regionIds list of String List of regionIds to delete

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to regionsChanged
data RegionsChanged OR ErrorResponse

Drivers API

List Drivers

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "drivers": {
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver1@example.com"
    },
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "id": "a08213e6-673f-4efc-955e-2bf587813162",
      "name": "Driver 2",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 31,
      "email": "driver2@example.com"
    }
  }
}

List all available Drivers (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/drivers

RETURN VALUES

Property Type Description
drivers map[UUID]Driver A map where the key is the driverId and the value is the associated Driver object

Add Driver

Add Driver Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "Driver 3",
  "email": "driver3@example.com",
  "password": "PhQ?Hqrt$4bs6_^2",
  "summarizeFutureMobileRoute": false,
  "mobileFutureDaysVisibility": -1
}

The above command returns JSON structured like this:

{
  "requestId": "74069cf8-6d58-416d-96ba-bbc9b48429c6"
}

And triggers a DriversChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "74069cf8-6d58-416d-96ba-bbc9b48429c6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [
      "0129724f-b80d-4011-ab91-3e4ae2f62896"
    ],
    "updated": [],
    "deleted": []
  }
}

Add one Driver (asynchronous).

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/drivers

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

REQUEST BODY

DriverInput

The system will assign a UUID to the Driver and return it in the driversChanged notification message in the created list

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to driversChanged
data DriversChanged OR ErrorResponse

Replace a Driver

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/0129724f-b80d-4011-ab91-3e4ae2f62896?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/0129724f-b80d-4011-ab91-3e4ae2f62896 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "Driver 3 - Replaced",
  "email": "driver3replaced@example.com",
  "password": "newpassword (optional: leave field blank to keep current password)",
  "summarizeFutureMobileRoute": false (optional, leave field blank to set to default (false)),
  "mobileFutureDaysVisibility": 2 (optional, leave field blank to set to default (2))
}

The above command returns JSON structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055"
}

And triggers a DriversChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [],
    "updated": [
      "0129724f-b80d-4011-ab91-3e4ae2f62896"
    ],
    "deleted": []
  }
}

Overwrite a Driver with new data (asynchronous).

If the updated Driver is logged on to the mobile application and the password is changed, she will be immediately logged out.

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/drivers/:driverId

REQUEST BODY

DriverInput object

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to driversChanged
data DriversChanged OR ErrorResponse

Update multiple Drivers

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "driverIds": ["0129724f-b80d-4011-ab91-3e4ae2f62896", "26b9989d-c053-45ec-9d98-906e55ff38f4"],
  "summarizeFutureMobileRoute": false,
  "mobileFutureDaysVisibility": 2
}

The above command returns JSON structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055"
}

And triggers a DriversChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "aae30294-8731-4dfb-93c9-6397d76c5055",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [],
    "updated": [
      "0129724f-b80d-4011-ab91-3e4ae2f62896",
      "26b9989d-c053-45ec-9d98-906e55ff38f4"
    ],
    "deleted": []
  }
}

Update some fields on multiple drivers at once (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/drivers

REQUEST BODY

Property Type Description
driverIds list of [String] List of Driver Ids to be updated
summarizeFutureMobileRoute Boolean Optional: if not set the old value will be kept. Manages the Mobile App visualization style of future routes. A summarized route shows only the first step, the last step, and the number of orders in between, without the detailed order list.
mobileFutureDaysVisibility Integer Optional: if not set the old value will be kept. Manages the Mobile App Future day visibility. Possible value: 2 or -1. -1 indicates all dispatchable days.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to driversChanged
data DriversChanged OR ErrorResponse

Delete a Driver

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/0129724f-b80d-4011-ab91-3e4ae2f62896?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/0129724f-b80d-4011-ab91-3e4ae2f62896 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "9cceb7c7-c6fb-4843-b8c9-608cf87964f9"
}

And triggers a DriversChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9cceb7c7-c6fb-4843-b8c9-608cf87964f9",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "0129724f-b80d-4011-ab91-3e4ae2f62896"
    ]
  }
}

Delete a Driver (asynchronous).

If the Driver is logged on to the mobile application she will be immediately logged out.
A Driver who sent any kind of tracking data on a not yet archived route cannot be deleted.

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/drivers/:driverId

RETURN VALUES (notification)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to driversChanged
data DriversChanged OR ErrorResponse

Vehicles API

List Vehicles

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "vehicles": {
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "idx": 1,
      "externalId": "Vehicle 1",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "009944",
      "settings": {
        "available": true,
        "notes": "",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "timeWindow": {
          "startSec": 28800,
          "endSec": 61200
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "maxLocations": 0,
        "maxStops": 0,
        "breaks": [],
        "loadCapacities": {
          "people": 600
        },
        "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
        "activationCost": 0,
        "drivingTimeCost": 2000,
        "idleTimeCost": 2000,
        "serviceTimeCost": 2000,
        "breakTimeCost": 2000,
        "kmCost": 100,
        "tags": [
          "heavy"
        ],
        "speedFactor": 100,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    },
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "sameSideOfStreet": false,
      "color": "5500FF"
      "settings": {
        "available": true,
        "notes": "",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "timeWindow": {
          "startSec": 28800,
          "endSec": 61200
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "breaks": [],
        "loadCapacities": {
          "frozen ton": 500,
          "regular ton": 500
        },
        "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
        "activationCost": 0,
        "drivingTimeCost": 2000,
        "idleTimeCost": 2000,
        "serviceTimeCost": 2000,
        "breakTimeCost": 2000,
        "kmCost": 100,
        "tags": [
          "frozen",
          "regular"
        ],
        "speedFactor": 100,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    }
  }
}

List all available Vehicles (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles

RETURN VALUES

Property Type Description
vehicles map[UUID] Vehicle A map where the key is the vehicleId and the value is the associated Vehicle object

Add Vehicles

Add Single Vehicle Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "vehicles": [
    {
      "externalId": "New Vehicle #1",
      "color": "c08e88",
      "tracked": true,
      "sameSideOfStreet": true,
      "gpsDeviceId": null,
      "settings": {
        "available": true,
        "notes": "Vehicle added via REST API",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "timeWindow": {
          "startSec": 28800,
          "endSec": 61200
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "maxLocations": 0,
        "maxStops": 0,
        "breaks": [],
        "loadCapacities": {
          "people": 1500
        },
        "regionIds": [],
        "activationCost": 10000,
        "drivingTimeCost": 2000,
        "idleTimeCost": 2000,
        "serviceTimeCost": 2000,
        "breakTimeCost": 2000,
        "kmCost": 100,
        "tags": [
          "light"
        ],
        "speedFactor": 130,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "b3557aeb-8698-4763-bc7b-97573e1fc58c"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "b3557aeb-8698-4763-bc7b-97573e1fc58c",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [
      {
        "id":"939b2fbb-f17e-4ed2-b1fa-b91dd9ae6525"
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add Multiple Vehicles Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "vehicles": [
    {
      "externalId": "New Vehicle #1",
      "color": "c08e88",
      "tracked": true,
      "sameSideOfStreet": true,
      "gpsDeviceId": null,
      "settings": {
        "available": true,
        "notes": "Vehicle added via REST API",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "timeWindow": {
          "startSec": 28800,
          "endSec": 61200
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "breaks": [],
        "loadCapacities": {
          "people": 1500
        },
        "regionIds": [],
        "activationCost": 10000,
        "drivingTimeCost": 2000,
        "idleTimeCost": 2000,
        "serviceTimeCost": 2000,
        "breakTimeCost": 2000,
        "kmCost": 100,
        "tags": [
          "light"
        ],
        "speedFactor": 130,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    },
    {
      "externalId": "New Vehicle #2",
      "color": "bb22ff",
      "tracked": true,
      "sameSideOfStreet": false,
      "gpsDeviceId": null,
      "settings": {
        "available": true,
        "notes": "Vehicle added via REST API",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": null,
        "timeWindow": {
          "startSec": 32400,
          "endSec": 54000
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "breaks": [],
        "loadCapacities": {
          "people": 3000
        },
        "regionIds": [],
        "activationCost": 20000,
        "drivingTimeCost": 3500,
        "idleTimeCost": 3500,
        "serviceTimeCost": 3500,
        "breakTimeCost": 3500,
        "kmCost": 140,
        "tags": [
          "medium"
        ],
        "speedFactor": 90,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "0cb57001-f179-419e-bbaf-14c912cf22a0"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "0cb57001-f179-419e-bbaf-14c912cf22a0",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [
      {
        "id":"9a773f55-b6f5-4c9f-b2d4-c813b24fe840",
      },
      {
        "id":"c05388f1-1295-4741-a444-706f958e7275",
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add one or more Vehicles (asynchronous).

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles

THROTTLING

Rate-limit (1 call every 60 seconds)

REQUEST BODY

Property Type Description
vehicles list of VehicleInput List of Vehicles to be added. The system will assign a UUID to each Vehicle and return it in the vehiclesChanged notification message in the created list (e.g.: the UUID assigned to the 3rd Vehicle in the input vehicles list is the 3rd UUID in the VehiclesChanged.created field)

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Delete a Vehicle

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/0d8855e6-28a0-4e89-9c67-b44c66c39ba6?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/0d8855e6-28a0-4e89-9c67-b44c66c39ba6 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "1c43aa53-4d03-4c92-bff0-ff1f9b7dad8c"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "1c43aa53-4d03-4c92-bff0-ff1f9b7dad8c",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
    ]
  }
}

Delete a Vehicle (asynchronous).

THROTTLING

Rate-limit (1 call every 60 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:vehicleId

RETURN VALUES (notification)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Delete Vehicles

curl -H "Content-Type: application/json" -X DELETE -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "ids": [
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "6941414f-068b-4d05-9627-a53645acc61a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "6941414f-068b-4d05-9627-a53645acc61a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
    ]
  }
}

Delete multiple Vehicles (asynchronous).

THROTTLING

Rate-limit (1 call every 60 seconds)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles[?ids=<comma_separated_list>]

REQUEST BODY

Property Type Description
ids list of String Ids of Vehicles to be deleted.

QUERYSTRING PARAMETERS [DEPRECATED]

Property Type Description
ids comma-separated list of String Ids of Vehicles to be deleted.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Get Vehicle Settings

Get Vehicle Settings for a given date (synchronous).

THROTTLING

Leaky bucket (size:20, refill: 3 per second)

Specific date

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7/20151203?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7/20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "settings": {
    "available": true,
    "notes": "",
    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "timeWindow": {
      "startSec": 28800,
      "endSec": 61200
    },
    "flexStartTime": true,
    "perStopCost": 0,
    "perStopTimeSec": 0,
    "maxWorkingTimeSec": 0,
    "maxDrivingTimeSec": 0,
    "maxDistanceMt": 0,
    "maxOrders": 0,
    "maxLocations": 0,
    "maxStops": 0,
    "breaks": [],
    "loadCapacities": {
      "people": 600
    },
    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
    "activationCost": 0,
    "drivingTimeCost": 2000,
    "idleTimeCost": 2000,
    "serviceTimeCost": 2000,
    "breakTimeCost": 2000,
    "kmCost": 100,
    "tags": [
      "heavy"
    ],
    "speedFactor": 100,
    "minWorkingTimeSec": 0,
    "minLoadCapacities": {},
    "preparationTimeSec": 0,
    "closeOutTimeSec": 0
  }
}

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:vehicleId/:date

PATH PARAMETERS

Property Type Description
date DateString Settings for this date are returned

RETURN VALUES

Property Type Description
settings VehicleSettings The settings object

Normal day

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "settings": {
    "available": true,
    "notes": "",
    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "timeWindow": {
      "startSec": 28800,
      "endSec": 61200
    },
    "flexStartTime": true,
    "perStopCost": 0,
    "perStopTimeSec": 0,
    "maxWorkingTimeSec": 0,
    "maxDrivingTimeSec": 0,
    "maxDistanceMt": 0,
    "maxOrders": 0,
    "maxLocations": 0,
    "maxStops": 0,
    "breaks": [],
    "loadCapacities": {
      "people": 600
    },
    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
    "activationCost": 0,
    "drivingTimeCost": 2000,
    "idleTimeCost": 2000,
    "serviceTimeCost": 2000,
    "breakTimeCost": 2000,
    "kmCost": 100,
    "tags": [
      "heavy"
    ],
    "speedFactor": 100,
    "minWorkingTimeSec": 0,
    "minLoadCapacities": {},
    "preparationTimeSec": 0,
    "closeOutTimeSec": 0
  }
}

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:vehicleId

RETURN VALUES

Property Type Description
settings VehicleSettings The settings object for normal day

List Vehicle Settings

List all Vehicle Settings for the given date (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:date

PATH PARAMETERS

Property Type Description
date DateString Settings for this date are returned

RETURN VALUES

Property Type Description
settings map[UUID]VehicleSettings A map where the key is the vehicleId and the value is the associated VehicleSettings object

Replace Vehicle Settings

Replace current Vehicle Settings with the given ones for the given date (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 every 2 seconds)

Specific date

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7/20151203?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7/20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "available": true,
  "notes": "updated via API",
  "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "timeWindow": {
    "startSec": 28800,
    "endSec": 61200
  },
  "flexStartTime": true,
  "perStopCost": 0,
  "perStopTimeSec": 0,
  "maxWorkingTimeSec": 0,
  "maxDrivingTimeSec": 0,
  "maxDistanceMt": 0,
  "maxOrders": 0,
  "maxLocations": 0,
  "maxStops": 0,
  "breaks": [
    {
      "startSec": 43200,
      "endSec": 48600,
      "durationSec": 1800
    }
  ],
  "loadCapacities": {
    "people": 600
  },
  "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
  "activationCost": 0,
  "drivingTimeCost": 2000,
  "idleTimeCost": 2000,
  "serviceTimeCost": 2000,
  "breakTimeCost": 2000,
  "kmCost": 100,
  "tags": [
    "heavy",
    "medium"
  ],
  "speedFactor": 120,
  "minWorkingTimeSec": 0,
  "minLoadCapacities": {},
  "preparationTimeSec": 600,
  "closeOutTimeSec": 0
}

The above command returns JSON structured like this:

{
  "requestId": "c8909d6c-c7b2-4f15-ac43-d0ae935de91a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "c8909d6c-c7b2-4f15-ac43-d0ae935de91a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
    ],
    "deleted": []
  }
}

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:vehicleId/:date

PATH PARAMETERS

Property Type Description
date DateString Settings for this date are replaced. Cannot be a past date and cannot be more than 10 days into the future

REQUEST BODY

VehicleSettings object

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Normal day

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "available": true,
  "notes": "normal day updated via API",
  "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "timeWindow": {
    "startSec": 28800,
    "endSec": 61200
  },
  "flexStartTime": true,
  "perStopCost": 0,
  "perStopTimeSec": 0,
  "maxWorkingTimeSec": 0,
  "maxDrivingTimeSec": 0,
  "maxDistanceMt": 0,
  "maxOrders": 0,
  "maxLocations": 0,
  "maxStops": 0,
  "breaks": [
    {
      "startSec": 43200,
      "endSec": 48600,
      "durationSec": 1800
    }
  ],
  "loadCapacities": {
    "people": 600
  },
  "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
  "activationCost": 0,
  "drivingTimeCost": 2000,
  "idleTimeCost": 2000,
  "serviceTimeCost": 2000,
  "breakTimeCost": 2000,
  "kmCost": 100,
  "tags": [
    "heavy",
    "medium"
  ],
  "speedFactor": 120,
  "minWorkingTimeSec": 0,
  "minLoadCapacities": {},
  "preparationTimeSec": 600,
  "closeOutTimeSec": 0
}

The above command returns JSON structured like this:

{
  "requestId": "c8909d6c-c7b2-4f15-ac43-d0ae935de91a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "c8909d6c-c7b2-4f15-ac43-d0ae935de91a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
    ],
    "deleted": []
  }
}

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:vehicleId

REQUEST BODY

VehicleSettings object for normal day

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Bulk Replace Vehicle Settings

Bulk-replace current Vehicle Settings with the given ones for the given date (asynchronous).

THROTTLING

Rate-limit (1 call every 5 seconds)

Specific date

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/20151203?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "settings": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "available": true,
      "notes": "settings for 2015-12-03 updated via REST API, bulk version",
      "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "timeWindow": {
        "startSec": 28800,
        "endSec": 61200
      },
      "flexStartTime": true,
      "perStopCost": 0,
      "perStopTimeSec": 0,
      "maxWorkingTimeSec": 0,
      "maxDrivingTimeSec": 0,
      "maxDistanceMt": 0,
      "maxOrders": 0,
      "maxLocations": 0,
      "maxStops": 0,
      "breaks": [
        {
          "startSec": 43200,
          "endSec": 48600,
          "durationSec": 1800
        }
      ],
      "loadCapacities": {
        "people": 600
      },
      "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
      "activationCost": 0,
      "drivingTimeCost": 2000,
      "idleTimeCost": 2000,
      "serviceTimeCost": 2000,
      "breakTimeCost": 2000,
      "kmCost": 100,
      "tags": [
        "heavy",
        "medium"
      ],
      "speedFactor": 120,
      "minWorkingTimeSec": 0,
      "minLoadCapacities": {},
      "preparationTimeSec": 600,
      "closeOutTimeSec": 0
    },
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "available": true,
      "notes": "settings for 2015-12-03 updated via REST API, bulk version",
      "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "timeWindow": {
        "startSec": 28800,
        "endSec": 61200
      },
      "flexStartTime": true,
      "perStopCost": 0,
      "perStopTimeSec": 0,
      "maxWorkingTimeSec": 0,
      "maxDrivingTimeSec": 0,
      "maxDistanceMt": 0,
      "maxOrders": 0,
      "maxLocations": 0,
      "maxStops": 0,
      "breaks": [
        {
          "startSec": 43200,
          "endSec": 48600,
          "durationSec": 1800
        }
      ],
      "loadCapacities": {
        "frozen ton": 500,
        "regular ton": 500
      },
      "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
      "activationCost": 0,
      "drivingTimeCost": 2500,
      "idleTimeCost": 2500,
      "serviceTimeCost": 3500,
      "breakTimeCost": 1500,
      "kmCost": 115,
      "tags": [
        "frozen",
        "regular"
      ],
      "speedFactor": 150,
      "minWorkingTimeSec": 0,
      "minLoadCapacities": {},
      "preparationTimeSec": 600,
      "closeOutTimeSec": 0
    }
  }
}

The above command returns JSON structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
    ],
    "deleted": []
  }
}

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/:date

PATH PARAMETERS

Property Type Description
date DateString Settings for this date are replaced. Cannot be a past date and cannot be more than 10 days into the future

REQUEST BODY

Property Type Description
settings map [UUID]VehicleSettings A map where keys are vehicleIds and values are the associated VehicleSettings objects

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Normal day

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "settings": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "available": true,
      "notes": "settings for 2015-12-03 updated via REST API, bulk version, normal day",
      "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "timeWindow": {
        "startSec": 28800,
        "endSec": 61200
      },
      "flexStartTime": true,
      "perStopCost": 0,
      "perStopTimeSec": 0,
      "maxWorkingTimeSec": 0,
      "maxDrivingTimeSec": 0,
      "maxDistanceMt": 0,
      "maxOrders": 0,
      "maxLocations": 0,
      "maxStops": 0,
      "breaks": [
        {
          "startSec": 43200,
          "endSec": 48600,
          "durationSec": 1800
        }
      ],
      "loadCapacities": {
        "people": 600
      },
      "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
      "activationCost": 0,
      "drivingTimeCost": 2000,
      "idleTimeCost": 2000,
      "serviceTimeCost": 2000,
      "breakTimeCost": 2000,
      "kmCost": 100,
      "tags": [
        "heavy",
        "medium"
      ],
      "speedFactor": 120,
      "minWorkingTimeSec": 0,
      "minLoadCapacities": {},
      "preparationTimeSec": 600,
      "closeOutTimeSec": 0
    },
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "available": true,
      "notes": "settings for 2015-12-03 updated via REST API, bulk version, normal day",
      "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "timeWindow": {
        "startSec": 28800,
        "endSec": 61200
      },
      "flexStartTime": true,
      "perStopCost": 0,
      "perStopTimeSec": 0,
      "maxWorkingTimeSec": 0,
      "maxDrivingTimeSec": 0,
      "maxDistanceMt": 0,
      "maxOrders": 0,
      "maxLocations": 0,
      "maxStops": 0,
      "breaks": [
        {
          "startSec": 43200,
          "endSec": 48600,
          "durationSec": 1800
        }
      ],
      "loadCapacities": {
        "frozen ton": 500,
        "regular ton": 500
      },
      "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
      "activationCost": 0,
      "drivingTimeCost": 2500,
      "idleTimeCost": 2500,
      "serviceTimeCost": 3500,
      "breakTimeCost": 1500,
      "kmCost": 115,
      "tags": [
        "frozen",
        "regular"
      ],
      "speedFactor": 150,
      "minWorkingTimeSec": 0,
      "minLoadCapacities": {},
      "preparationTimeSec": 600,
      "closeOutTimeSec": 0
    }
  }
}

The above command returns JSON structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
    ],
    "deleted": []
  }
}

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles

REQUEST BODY

Property Type Description
settings map [UUID]VehicleSettings A map where keys are vehicleIds and values are the associated VehicleSettings objects for normal day

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Update Vehicles Details

Update details of one or more Vehicles.

This API works like a partial update. If a key is missing from VehicleDetails the corresponding field of the vehicle will not be updated.

THROTTLING

Leaky bucket (size: 10, refill: 1 per second)

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/details?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/details HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json


{
    "details": [
        {
            "id": "e3980635-9d45-4438-a496-4805b92f0c32",
            "tracked": true
        },
        {
          "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
          "externalId": "Test Vehicle"
        },
        {
          "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
          "color": "ff0000"
        }
    ]
}

The above command returns JSON structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a"
}

And triggers a VehiclesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "1218f84f-ac09-4314-9e9f-353e5fabbf8a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
    ],
    "deleted": []
  }
}

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicles/details

REQUEST BODY

Property Type Description
details list of VehicleDetails The list of changes to apply

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse

Vehicle-Driver Assignments API

Get Driver Assignments

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicledriverassignments/20151203?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicledriverassignments/20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "assignments": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": "a3935987-4944-462f-b602-4a3a12beeeff",
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": "a08213e6-673f-4efc-955e-2bf587813162"
  }
}

Get all vehicle-to-driver assignments for the given date (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicledriverassignments/:date

PATH PARAMETERS

Property Type Description
date DateString Assignments for this date are returned

RETURN VALUES

Property Type Description
assignments map[UUID] [UUID] A map where the key is the vehicleId and the value is the associated driverId

Replace Driver Assignments

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/20151203?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/drivers/20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "assignments": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": "a08213e6-673f-4efc-955e-2bf587813162",
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": "a3935987-4944-462f-b602-4a3a12beeeff"
  }
}

The above command returns JSON structured like this:

{
  "requestId": "c1b9fe04-9ab2-4aac-9a9b-055c63070319"
}

And triggers an VehicleDriverAssignmentsChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "c1b9fe04-9ab2-4aac-9a9b-055c63070319",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehicleDriverAssignmentsChanged",
  "data": {}
}

Replace all existing vehicle-to-driver assignments for the given date with new ones (asynchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per 10 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/vehicledriverassignments/:date

PATH PARAMETERS

Property Type Description
date DateString Assignments for this date are replaced. Cannot be a past date and cannot be more than 10 days into the future

REQUEST BODY

Property Type Description
assignments map [UUID] [UUID] A map where keys are vehicleIds and values are the associated driverIds

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehicleDriverAssignmentsChanged
data empty object OR ErrorResponse

Orders API

Operations

List Orders

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY&include=all

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "orders": {
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21": {
      "id": "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3": {
      "id": "0d56e7a3-c737-472e-bec9-e2f19d4865d3",
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA",
          "latLng": [
            33845214,
            -87273604
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Demonstrate the concept of priority and notes (Driver must use the back door to enter the building)",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "407df645-bca8-4d3d-aa84-6dafcf1296a4": {
      "id": "407df645-bca8-4d3d-aa84-6dafcf1296a4",
      "name": "Order 3",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 10,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "710 7th Ave, Jasper, AL 35504, USA",
          "latLng": [
            33849682,
            -87282890
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 39600,
            "endSec": 46800
          }
        ],
        "notes": "demonstrate the concept of custom Fields",
        "serviceTimeSec": 300,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Phone Extensions ": "76"
        }
      },
      "isService": false
    },
    "c5b66e27-eb70-43fb-be54-37a2f7ef723e": {
      "id": "c5b66e27-eb70-43fb-be54-37a2f7ef723e",
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery (meaning that the Vehicle servicing it will pick up loads at one location and delivered them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    "0f397b30-b068-4e4f-8d78-d4b0c231e6c1": {
      "id": "0f397b30-b068-4e4f-8d78-d4b0c231e6c1",
      "name": "Order 5",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": null,
          "latLng": [
            33847059,
            -87296707
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of using coordinates(longitude and latitude) data instead of address",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "903a7eda-b27d-499c-b70c-58258449470a": {
      "id": "903a7eda-b27d-499c-b70c-58258449470a",
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": null,
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle to serve an order, apply different eligibility type ",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "f8ad4ee8-89b6-4e57-8d5d-3c0838d03ea7": {
      "id": "f8ad4ee8-89b6-4e57-8d5d-3c0838d03ea7",
      "name": "Order 7",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
          "latLng": [
            33843834,
            -87315561
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of tags in/out",
        "serviceTimeSec": 1800,
        "tagsIn": [
          "frozen",
          "regular"
        ],
        "tagsOut": [
          "heavy"
        ],
        "customFields": {}
      },
      "isService": false
    }
  },
  "depots": {}
}

List current (not yet archived) Orders, optionally filtering them by a set of criteria (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/orders[?include=all|assigned|unassigned][&eligibleOn=YYYYMMDD][&assignedOn=YYYYMMDD]

QUERYSTRING PARAMETERS
Property Type Description
include enum Optional. If not specified defaults to “all”. Can be one of:
“all”: include all current (not archived) Orders
“assigned”: include only Orders that are assigned to a Route
“unassigned”: include only Orders that are not assigned to a Route
An Order is considered “assigned” if it is associated to a Route and therefore is or will be visited by a Vehicle driven by a Driver
Note: if an Order that is part of a Route ends up being skipped by the Vehicle that is supposed to visit it, it will still fall in the “assigned” category. That is to say that “assigned” actually means “planned as assigned”
Note: if an Order defines both pickup and delivery OrderSteps, but only one of them is associated to a Route, the Order will be listed in both “assigned” and “unassigned” categories
eligibleOn DateString Optional. Includes only current (not archived) Orders whose eligibility matches the given date.
If the filter date is 20170320, then the following Orders will be matched:
- Order eligible “on” 20170318, 20170320 and 20170325
- Order eligible “by” 20170320
- Order eligible “by” 20170324
- Order eligible on “any” date
assignedOn DateString Optional. Includes only current (not archived) Orders that are assigned to Routes on the given date.
Note: if set, overrides the “include” parameter forcing it to “assigned”
Note: if Routes on the specified date are archived the returned list will be empty
RETURN VALUES
Property Type Description
orders map[UUID]Order A map where the key is the orderId and the value is the associated Order object
depots map[UUID]Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders (if any)

Get Orders

curl -H "Content-Type: application/json" -X GET -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

{
  "ids": [
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3"
  ]
}

The above command returns JSON structured like this:

{
  "orders": {
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21": {
      "id": "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3": {
      "id": "0d56e7a3-c737-472e-bec9-e2f19d4865d3",
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA",
          "latLng": [
            33845214,
            -87273604
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Demonstrate the concept of priority and notes (Driver must use the back door to enter the building)",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "depots": {}
}

Get the given Orders (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/orders

REQUEST BODY
Property Type Description
ids list of String Optional. If not specified or empty all current Orders are returned
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
ids comma-separated list of String Optional. If not specified or empty all current Orders are returned.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES
Property Type Description
orders map[UUID]Order A map where the key is the orderId and the value is the associated Order object
depots map[UUID]Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders (if any)

Add Orders

Add Single Order Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "name": "Order 6 - API",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "people": 2
      },
      "delivery": {
        "location": {
          "address": "2001 2nd Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ],
        "notes": "Order added via API",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "my custom field": "custom field content",
          "orderId": "abcd1234"
        },
        "barcodes": ["1234567890128"]
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [
      {
        "id":"fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery":"OK"
        }
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add Multiple Orders Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Driver must use the back door to enter the building. Demonstrate the concept of notes and priority",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 3",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 10,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "gibberish gibberish gibberish"
        },
        "timeWindows": [
          {
            "startSec": 39600,
            "endSec": 46800
          }
        ],
        "notes": "Demonstrates the concept of Custom Fields & the result of an invalid address",
        "serviceTimeSec": 300,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Phone Extensions ": "76"
        }
      },
      "isService": false
    },
    {
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ]
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery (meaning that the Vehicle servicing it will pick up loads at one location and deliver them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ]
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    {
      "name": "Order 5",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "latLng": [
            33847059,
            -87296707
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of using coordinates(longitude and latitude) data instead of address",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "latLng": [
            33480873,
            -86788220
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of forceful vehicle assignment",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    {
      "name": "Order 7",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
          "latLng": [
            33843834,
            -87315561
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of tags in/out",
        "serviceTimeSec": 1800,
        "tagsIn": [
          "frozen",
          "regular"
        ],
        "tagsOut": [
          "heavy"
        ],
        "customFields": {}
      },
      "isService": false
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "0092906c-7416-43a5-8253-13ef2318b773"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "0092906c-7416-43a5-8253-13ef2318b773",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [
      {
        "id":"17646990-e888-4e81-8d36-88976e1e3cfa",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"be928f79-10ea-4c3e-94cc-48d3672ed7a0",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":null,
        "geocodeStatus": {
          "delivery":"NOT_FOUND"
        }
      },
      {
        "id":"d046b2cd-6b92-425d-ad47-80ae36b73220",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"392bbf0b-8ba0-4c9e-b18b-dc7968a8600a",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"c3653ce3-60d5-43a5-b68d-8c28988d1a26",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"df365bcd-37b8-4b22-920c-649fbec569b6",
        "geocodeStatus": {
          "delivery":"OK"
        }
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add one or more Orders (asynchronous).

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/orders

THROTTLING

Leaky bucket (size:60, refill: 1 per second)

REQUEST BODY
Property Type Description
orders list of OrderInput List of Orders to be added. The system will assign a UUID to each Order and return it in the ordersChanged notification message in the created list (e.g.: the UUID assigned to the 3rd Order in the input orders list is the 3rd UUID in the OrdersChanged.created field)
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, a time window spanning more than 24 hours, etc), the request fails and no Orders are added. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be added because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are added. Orders with an address that failed to be geocoded are not added (unless acceptBadGeocodes is true) and their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains failure details.
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are added regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace an Order

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "Order 6 - Replaced",
  "eligibility": {
    "type": "on",
    "onDates": [
      "20151204"
    ]
  },
  "forceVehicleId": null,
  "priority": 0,
  "loads": {
    "people": 6
  },
  "delivery": {
    "location": {
      "address": "2002 2nd Ave, Jasper, AL 35501, USA"
    },
    "timeWindows": [
      {
        "startSec": 43200,
        "endSec": 54000
      }
    ],
    "notes": "Order replaced via API",
    "serviceTimeSec": 900,
    "tagsIn": [],
    "tagsOut": [],
    "customFields": {
      "my custom field": "custom field content",
      "orderId": "abcd1234"
    }
  },
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite an Order with new data (asynchronous).

If the Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:60, refill: 20 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/orders/:orderId

REQUEST BODY

OrderInput object

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace Orders

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "name": "Order 6 - Replaced",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "people": 6
      },
      "delivery": {
        "location": {
          "address": "2002 2nd Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ],
        "notes": "Order replaced via API",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "my custom field": "custom field content",
          "orderId": "abcd1234"
        }
      }
    },
    {
      "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
      "name": "Order 1 - Replaced",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          }
        ],
        "notes": "removed one time window and restricted eligibility to one day",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  ],
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      },
      {
        "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite multiple Orders with new data (asynchronous).

If a replaced Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:10, refill: 10 per minute)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/orders

REQUEST BODY
Property Type Description
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, removed both pickup and delivery fields, etc), the request fails and no Orders are updated. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be updated because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are modified. Orders with an address that failed to be geocoded are not updated (unless acceptBadGeocodes flag is true and they are not scheduled within a Route) and their corresponding index in the updated list returned by the asynchronous notification contains a ChangedOrder entry where id is the null and error contains failure details.
orders list of Order List of replacement Orders
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace an OrderStep

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "location": {
    "address": "2007 2nd Ave, Jasper, AL 35501, USA"
  },
  "timeWindows": [
    {
      "startSec": 43200,
      "endSec": 54000
    }
  ],
  "notes": "Delivery OrderStep replaced via API",
  "serviceTimeSec": 1800,
  "tagsIn": [],
  "tagsOut": [],
  "customFields": {},
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "408d680e-d404-4a81-9d49-da1fd74ec66f"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "408d680e-d404-4a81-9d49-da1fd74ec66f",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite an OrderStep with new data (asynchronous).

THROTTLING

Leaky bucket (size:60, refill: 20 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/orders/:orderId/:orderStepType

PATH PARAMETERS
Property Type Description
orderId UUID The Order ID
orderStepType enum Can be pickup or delivery
REQUEST BODY

OrderStepInput object

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Update an Order

curl -H "Content-Type: application/json" -X PATCH -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

PATCH /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "loads": {
    "people": 6
  },
  "delivery": {
    "location": {
      "address": "2002 2nd Ave, Jasper, AL 35501, USA"
    },
    "timeWindows": [
      {
        "startSec": 43200,
        "endSec": 54000
      }
    ]
  },
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Partially update an Order with new data (asynchronous).

If the Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:10, refill: 20 per minute)

HTTP REQUEST

PATCH https://wwrm.workwave.com/api/v1/territories/:territoryId/orders/:orderId

REQUEST BODY

OrderInput object

The Order(Input) and its pickup/delivery OrderSteps are interpreted differently from the Replace an Order API. A key should be present in the json objects only if the corresponding value has to be updated, otherwise the key should be omitted (not set to null, since that would mean “update the value to null”).

Specifying any field of Order(Input) or OrderStep will replace the value for that field, except for the OrderStep fields timeWindowExceptions, and customFields; for those only the specified keys are updated. For example

{"pickup": {"tagsIn": ["tagA"]}}

will replace the entire list of tagsIn of the pickup with ["tagA"], while

{"pickup": {"customFields": {"exampleA": "a", "exampleB": null}}}

will add/update the custom field “exampleA” with “a” and will remove “exampleB”, but will leave all the other custom fields of the pickup unchanged.

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Update Orders

curl -H "Content-Type: application/json" -X PATCH -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

PATCH /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "strict": false,
  "orders": [
    {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "loads": {
        "people": 6
      },
      "delivery": {
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ]
      }
    },
    {
      "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
      "delivery": {
        "serviceTimeSec": 600
      }
    }
  ],
  "acceptBadGeocodes" : true

The above command returns JSON structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      },
      {
        "error": {
          "errorCode": 100,
          "errorMessage": "order[id:17646990-e888-4e81-8d36-88976e1e3cfa].name cannot be null"
        },
        "id": null,
        "geocodeStatus": {
          "delivery": "OK"
        },
        "pickup": null,
        "delivery": {
          "location": "OK",
          "email": "VALID",
          "phone": "VALID"
        }
      }
    ],
    "deleted": []
  }
}

Partially update multiple Orders with new data (asynchronous).

If an updated Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

If the input list contains any duplicate Order, the strict flag is ignored and an error is returned without making any modification.

THROTTLING

Leaky bucket (size:10, refill: 2 per minute)

HTTP REQUEST

PATCH https://wwrm.workwave.com/api/v1/territories/:territoryId/orders

REQUEST BODY
Property Type Description
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, removed both pickup and delivery fields, etc), the request fails and no Orders are updated. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be updated because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are modified. Orders with an address that failed to be geocoded are not updated (unless acceptBadGeocodes flag is true and they are not scheduled within a Route) and their corresponding index in the updated list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains failure details.
orders list of Order List of replacement Orders
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.

The Orders in the list are interpreted like the Order the Update an Order API body.

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete an Order

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7"
    ]
  }
}

Delete an Order (asynchronous).

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/orders/:orderId

RETURN VALUES (notification)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete Orders

curl -H "Content-Type: application/json" -X DELETE -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "ids": [
    "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "30427810-0672-4fd7-b56a-92698860a7f5"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "30427810-0672-4fd7-b56a-92698860a7f5",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
    ]
  }
}

Delete multiple Orders (asynchronous).

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/orders[?ids=<comma_separated_list>]

REQUEST BODY
Property Type Description
ids list of String Ids of Orders to be deleted.
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
ids comma-separated list of String Ids of Orders to be deleted.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete an OrderStep

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

// If the removed OrderStep was the only OrderStep, the Order is deleted:
{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7"
    ]
  }
}

// If the Order had both pickup and delivery OrderSteps, removing one (say, the delivery) updates the Order:
{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "pickup": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Delete an OrderStep (asynchronous).

If the OrderStep is the only one belonging to the Order, the Order itself is deleted.

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/orders/:orderId/:orderStepType

PATH PARAMETERS
Property Type Description
orderId UUID Identifies the Order
orderStepType enum Identifies the OrderStep. Can be pickup or delivery
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Simulations

List Orders

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY&include=all

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "orders": {
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21": {
      "id": "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3": {
      "id": "0d56e7a3-c737-472e-bec9-e2f19d4865d3",
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA",
          "latLng": [
            33845214,
            -87273604
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Demonstrate the concept of priority and notes (Driver must use the back door to enter the building)",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "407df645-bca8-4d3d-aa84-6dafcf1296a4": {
      "id": "407df645-bca8-4d3d-aa84-6dafcf1296a4",
      "name": "Order 3",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 10,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "710 7th Ave, Jasper, AL 35504, USA",
          "latLng": [
            33849682,
            -87282890
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 39600,
            "endSec": 46800
          }
        ],
        "notes": "demonstrate the concept of custom Fields",
        "serviceTimeSec": 300,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Phone Extensions ": "76"
        }
      },
      "isService": false
    },
    "c5b66e27-eb70-43fb-be54-37a2f7ef723e": {
      "id": "c5b66e27-eb70-43fb-be54-37a2f7ef723e",
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery (meaning that the Vehicle servicing it will pick up loads at one location and delivered them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    "0f397b30-b068-4e4f-8d78-d4b0c231e6c1": {
      "id": "0f397b30-b068-4e4f-8d78-d4b0c231e6c1",
      "name": "Order 5",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": null,
          "latLng": [
            33847059,
            -87296707
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of using coordinates(longitude and latitude) data instead of address",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "903a7eda-b27d-499c-b70c-58258449470a": {
      "id": "903a7eda-b27d-499c-b70c-58258449470a",
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": null,
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle to serve an order, apply different eligibility type ",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "f8ad4ee8-89b6-4e57-8d5d-3c0838d03ea7": {
      "id": "f8ad4ee8-89b6-4e57-8d5d-3c0838d03ea7",
      "name": "Order 7",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
          "latLng": [
            33843834,
            -87315561
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of tags in/out",
        "serviceTimeSec": 1800,
        "tagsIn": [
          "frozen",
          "regular"
        ],
        "tagsOut": [
          "heavy"
        ],
        "customFields": {}
      },
      "isService": false
    }
  },
  "depots": {}
}

List current Orders, optionally filtering them by a set of criteria (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders[?include=all|assigned|unassigned][&eligibleOn=YYYYMMDD][&assignedOn=YYYYMMDD]

QUERYSTRING PARAMETERS
Property Type Description
include enum Optional. If not specified defaults to “all”. Can be one of:
“all”: include all current (not archived) Orders
“assigned”: include only Orders that are assigned to a Route
“unassigned”: include only Orders that are not assigned to a Route
An Order is considered “assigned” if it is associated to a Route and therefore is or will be visited by a Vehicle driven by a Driver
Note: if an Order that is part of a Route ends up being skipped by the Vehicle that is supposed to visit it, it will still fall in the “assigned” category. That is to say that “assigned” actually means “planned as assigned”
Note: if an Order defines both pickup and delivery OrderSteps, but only one of them is associated to a Route, the Order will be listed in both “assigned” and “unassigned” categories
eligibleOn DateString Optional. Includes only current (not archived) Orders whose eligibility matches the given date.
If the filter date is 20170320, then the following Orders will be matched:
- Order eligible “on” 20170318, 20170320 and 20170325
- Order eligible “by” 20170320
- Order eligible “by” 20170324
- Order eligible on “any” date
assignedOn DateString Optional. Includes only current (not archived) Orders that are assigned to Routes on the given date.
Note: if set, overrides the “include” parameter forcing it to “assigned”
Note: if Routes on the specified date are archived the returned list will be empty
RETURN VALUES
Property Type Description
orders map[UUID]Order A map where the key is the orderId and the value is the associated Order object
depots map[UUID]Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders (if any)

Get Orders

curl -H "Content-Type: application/json" -X GET -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

{
  "ids": [
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3"
  ]
}

The above command returns JSON structured like this:

{
  "orders": {
    "4516b2e1-43dc-49a8-8bfb-7190fa60df21": {
      "id": "4516b2e1-43dc-49a8-8bfb-7190fa60df21",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0d56e7a3-c737-472e-bec9-e2f19d4865d3": {
      "id": "0d56e7a3-c737-472e-bec9-e2f19d4865d3",
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA",
          "latLng": [
            33845214,
            -87273604
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Demonstrate the concept of priority and notes (Driver must use the back door to enter the building)",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "depots": {}
}

Get the given Orders (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders

REQUEST BODY
Property Type Description
ids list of String Optional. If not specified or empty all current Orders are returned
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
ids comma-separated list of String Optional. If not specified or empty all current Orders are returned.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES
Property Type Description
orders map[UUID]Order A map where the key is the orderId and the value is the associated Order object
depots map[UUID]Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders (if any)

Add Orders

Add Single Order Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "name": "Order 6 - API",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "people": 2
      },
      "delivery": {
        "location": {
          "address": "2001 2nd Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ],
        "notes": "Order added via API",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "my custom field": "custom field content",
          "orderId": "abcd1234"
        },
        "barcodes": ["1234567890128"]
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [
      {
        "id":"fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery":"OK"
        }
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add Multiple Orders Request

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 20,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "701-799 Birmingham Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 32400,
            "endSec": 43200
          }
        ],
        "notes": "Driver must use the back door to enter the building. Demonstrate the concept of notes and priority",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 3",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 10,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "gibberish gibberish gibberish"
        },
        "timeWindows": [
          {
            "startSec": 39600,
            "endSec": 46800
          }
        ],
        "notes": "Demonstrates the concept of Custom Fields & the result of an invalid address",
        "serviceTimeSec": 300,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Phone Extensions ": "76"
        }
      },
      "isService": false
    },
    {
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ]
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery (meaning that the Vehicle servicing it will pick up loads at one location and deliver them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ]
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    {
      "name": "Order 5",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "latLng": [
            33847059,
            -87296707
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of using coordinates(longitude and latitude) data instead of address",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    {
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "latLng": [
            33480873,
            -86788220
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of forceful vehicle assignment",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    {
      "name": "Order 7",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
          "latLng": [
            33843834,
            -87315561
          ]
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of tags in/out",
        "serviceTimeSec": 1800,
        "tagsIn": [
          "frozen",
          "regular"
        ],
        "tagsOut": [
          "heavy"
        ],
        "customFields": {}
      },
      "isService": false
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "0092906c-7416-43a5-8253-13ef2318b773"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "0092906c-7416-43a5-8253-13ef2318b773",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [
      {
        "id":"17646990-e888-4e81-8d36-88976e1e3cfa",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"be928f79-10ea-4c3e-94cc-48d3672ed7a0",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":null,
        "geocodeStatus": {
          "delivery":"NOT_FOUND"
        }
      },
      {
        "id":"d046b2cd-6b92-425d-ad47-80ae36b73220",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"392bbf0b-8ba0-4c9e-b18b-dc7968a8600a",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"c3653ce3-60d5-43a5-b68d-8c28988d1a26",
        "geocodeStatus": {
          "delivery":"OK"
        }
      },
      {
        "id":"df365bcd-37b8-4b22-920c-649fbec569b6",
        "geocodeStatus": {
          "delivery":"OK"
        }
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Add one or more Orders (asynchronous).

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders

THROTTLING

Leaky bucket (size:60, refill: 1 per second)

REQUEST BODY
Property Type Description
orders list of OrderInput List of Orders to be added. The system will assign a UUID to each Order and return it in the ordersChanged notification message in the created list (e.g.: the UUID assigned to the 3rd Order in the input orders list is the 3rd UUID in the OrdersChanged.created field)
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, a time window spanning more than 24 hours, etc), the request fails and no Orders are added. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be added because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are added. Orders with an address that failed to be geocoded are not added (unless acceptBadGeocodes is true) and their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains failure details.
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are added regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace an Order

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "name": "Order 6 - Replaced",
  "eligibility": {
    "type": "on",
    "onDates": [
      "20151204"
    ]
  },
  "forceVehicleId": null,
  "priority": 0,
  "loads": {
    "people": 6
  },
  "delivery": {
    "location": {
      "address": "2002 2nd Ave, Jasper, AL 35501, USA"
    },
    "timeWindows": [
      {
        "startSec": 43200,
        "endSec": 54000
      }
    ],
    "notes": "Order replaced via API",
    "serviceTimeSec": 900,
    "tagsIn": [],
    "tagsOut": [],
    "customFields": {
      "my custom field": "custom field content",
      "orderId": "abcd1234"
    }
  },
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite an Order with new data (asynchronous).

If the Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:60, refill: 20 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders/:orderId

REQUEST BODY

OrderInput object

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace Orders

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

PUT /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orders": [
    {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "name": "Order 6 - Replaced",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "people": 6
      },
      "delivery": {
        "location": {
          "address": "2002 2nd Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ],
        "notes": "Order replaced via API",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "my custom field": "custom field content",
          "orderId": "abcd1234"
        }
      }
    },
    {
      "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
      "name": "Order 1 - Replaced",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          }
        ],
        "notes": "removed one time window and restricted eligibility to one day",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  ],
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      },
      {
        "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite multiple Orders with new data (asynchronous).

If a replaced Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:10, refill: 10 per minute)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders

REQUEST BODY
Property Type Description
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, removed both pickup and delivery fields, etc), the request fails and no Orders are updated. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be updated because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are modified. Orders with an address that failed to be geocoded are not updated (unless acceptBadGeocodes flag is true and they are not scheduled within a Route) and their corresponding index in the updated list returned by the asynchronous notification contains a ChangedOrder entry where id is the null and error contains failure details.
orders list of Order List of replacement Orders
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Replace an OrderStep

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "location": {
    "address": "2007 2nd Ave, Jasper, AL 35501, USA"
  },
  "timeWindows": [
    {
      "startSec": 43200,
      "endSec": 54000
    }
  ],
  "notes": "Delivery OrderStep replaced via API",
  "serviceTimeSec": 1800,
  "tagsIn": [],
  "tagsOut": [],
  "customFields": {},
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "408d680e-d404-4a81-9d49-da1fd74ec66f"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "408d680e-d404-4a81-9d49-da1fd74ec66f",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Overwrite an OrderStep with new data (asynchronous).

THROTTLING

Leaky bucket (size:60, refill: 20 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders/:orderId/:orderStepType

PATH PARAMETERS
Property Type Description
orderId UUID The Order ID
orderStepType enum Can be pickup or delivery
REQUEST BODY

OrderStepInput object

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Update an Order

curl -H "Content-Type: application/json" -X PATCH -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

PATCH /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "loads": {
    "people": 6
  },
  "delivery": {
    "location": {
      "address": "2002 2nd Ave, Jasper, AL 35501, USA"
    },
    "timeWindows": [
      {
        "startSec": 43200,
        "endSec": 54000
      }
    ]
  },
  "acceptBadGeocodes" : true
}

The above command returns JSON structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Partially update an Order with new data (asynchronous).

If the Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

THROTTLING

Leaky bucket (size:10, refill: 20 per minute)

HTTP REQUEST

PATCH https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders/:orderId

REQUEST BODY

OrderInput object

The Order(Input) and its pickup/delivery OrderSteps are interpreted differently from the Replace an Order API. A key should be present in the json objects only if the corresponding value has to be updated, otherwise the key should be omitted (not set to null, since that would mean “update the value to null”).

Specifying any field of Order(Input) or OrderStep will replace the value for that field, except for the OrderStep fields timeWindowExceptions, and customFields; for those only the specified keys are updated. For example

{"pickup": {"tagsIn": ["tagA"]}}

will replace the entire list of tagsIn of the pickup with ["tagA"], while

{"pickup": {"customFields": {"exampleA": "a", "exampleB": null}}}

will add/update the custom field “exampleA” with “a” and will remove “exampleB”, but will leave all the other custom fields of the pickup unchanged.

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Update Orders

curl -H "Content-Type: application/json" -X PATCH -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

PATCH /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "strict": false,
  "orders": [
    {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "loads": {
        "people": 6
      },
      "delivery": {
        "timeWindows": [
          {
            "startSec": 43200,
            "endSec": 54000
          }
        ]
      }
    },
    {
      "id": "17646990-e888-4e81-8d36-88976e1e3cfa",
      "delivery": {
        "serviceTimeSec": 600
      }
    }
  ],
  "acceptBadGeocodes" : true

The above command returns JSON structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "95452e2e-e358-4472-b10e-6083a5174199",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      },
      {
        "error": {
          "errorCode": 100,
          "errorMessage": "order[id:17646990-e888-4e81-8d36-88976e1e3cfa].name cannot be null"
        },
        "id": null,
        "geocodeStatus": {
          "delivery": "OK"
        },
        "pickup": null,
        "delivery": {
          "location": "OK",
          "email": "VALID",
          "phone": "VALID"
        }
      }
    ],
    "deleted": []
  }
}

Partially update multiple Orders with new data (asynchronous).

If an updated Order is part of a Route, Time Of Arrival information for that Route might change accordingly (e.g.: if the new data changes the service time or the address of the Order).

If the input list contains any duplicate Order, the strict flag is ignored and an error is returned without making any modification.

THROTTLING

Leaky bucket (size:10, refill: 2 per minute)

HTTP REQUEST

PATCH https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders

REQUEST BODY
Property Type Description
strict boolean Optional, defaults to true.

When set to true and one or more Orders do not pass formal validation checks (e.g.: eligibility date set in the past, removed both pickup and delivery fields, etc), the request fails and no Orders are updated. Details about the failed validation are reported in the asynchronous error notification.

When set to false Orders that do not pass formal validation checks are skipped without causing the whole request to fail. Their corresponding index in the created list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains details about the validation problem
IMPORTANT: If formal data validation is ok but one or more Orders still cannot be updated because of a wrong or non-existing address, the request is accepted and all Orders with a valid address are modified. Orders with an address that failed to be geocoded are not updated (unless acceptBadGeocodes flag is true and they are not scheduled within a Route) and their corresponding index in the updated list returned by the asynchronous notification contains a ChangedOrder entry where id is null and error contains failure details.
orders list of Order List of replacement Orders
acceptBadGeocodes boolean Optional, defaults to false.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.

The Orders in the list are interpreted like the Order the Update an Order API body.

RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete an Order

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7"
    ]
  }
}

Delete an Order (asynchronous).

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders/:orderId

RETURN VALUES (notification)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete Orders

curl -H "Content-Type: application/json" -X DELETE -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "ids": [
    "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "30427810-0672-4fd7-b56a-92698860a7f5"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "30427810-0672-4fd7-b56a-92698860a7f5",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
    ]
  }
}

Delete multiple Orders (asynchronous).

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders[?ids=<comma_separated_list>]

REQUEST BODY
Property Type Description
ids list of String Ids of Orders to be deleted.
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
ids comma-separated list of String Ids of Orders to be deleted.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Delete an OrderStep

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/delivery?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695"
}

And triggers an OrdersChanged Notification (POSTed to the callback URL) structured like this:

// If the removed OrderStep was the only OrderStep, the Order is deleted:
{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7"
    ]
  }
}

// If the Order had both pickup and delivery OrderSteps, removing one (say, the delivery) updates the Order:
{
  "requestId": "92c467fb-aa24-4f19-b934-18a3ebac0695",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "pickup": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Delete an OrderStep (asynchronous).

If the OrderStep is the only one belonging to the Order, the Order itself is deleted.

THROTTLING

Leaky bucket (size:20, refill: 20 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/orders/:orderId/:orderStepType

PATH PARAMETERS
Property Type Description
orderId UUID Identifies the Order
orderStepType enum Identifies the OrderStep. Can be pickup or delivery
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse

Time Of Arrival API

Operations

List Current Routes

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/routes?key=AUTH_KEY&date=20151112

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/routes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "routes": {
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
      "revision": 182,
      "date": "20151204",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 32329,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": -1,
          "trackingData": {
            "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
            "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
            "timeInSec": 28800,
            "timeInLatLng": [
              33817872,
              -87266893
            ],
            "timeOutSec": 29400,
            "timeOutLatLng":  [
              33817872,
              -87266893
            ]
          }
        },
        {
          "type": "delivery",
          "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 34200,
          "startSec": 34200,
          "endSec": 36000,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 1,
          "displayLabel": "1.1",
          "trackingData": {
            "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
            "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
            "timeInSec": 34526,
            "timeInLatLng": [
              33817872,
              -87266893
            ],
            "timeOutSec": -1,
            "timeOutLatLng": null,
            "status": "done",
            "statusSec": 35912,
            "statusLatLng": [
              33817872,
              -87266893
            ],
            "statusReason": null,
            "timeInDetectedSec": 34201,
            "timeInDetectedLatLng": [
              33817942,
              -87266921
            ],
            "timeOutDetectedSec": 35935,
            "timeOutDetectedLatLng": [
              33817404,
              -87266657
            ]
          }
        },
        {
          "type": "pickup",
          "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 39600,
          "startSec": 39600,
          "endSec": 40600,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 2,
          "displayLabel": "1.2",
          "trackingData": {
            "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
            "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
            "timeInSec": 39600,
            "timeInLatLng": [
              33480873,
              -86788220
            ],
            "timeOutSec": 40720,
            "timeOutLatLng": [
              33480873,
              -86788220
            ],
            "status": "done",
            "statusSec": 40780,
            "statusLatLng": [
              33480873,
              -86788220
            ],
            "statusReason": null,
            "timeInDetectedSec": 39582,
            "timeInDetectedLatLng": [
              33481223,
              -86787985
            ],
            "timeOutDetectedSec": 40795,
            "timeOutDetectedLatLng": [
              33481223,
              -86788790
            ]
          }
        }
      ],
      "trackingData": {
        "driversTrackingData": {
          "a08213e6-673f-4efc-955e-2bf587813162": {
            "current": {
              "departure": {
                "sec": 32329,
                "latLng": [
                  33817872,
                  -87266893
                ]
              },
              "arrival": {
                "sec": 40851,
                "latLng": [
                  33817942,
                  -87266921
                ]
              }
            },
            "history": [
              {
                "eventType": "departure",
                "action": "upsert",
                "fix": {
                  "sec": 28800,
                  "latLng": [
                    33817872,
                    -87266893
                  ]
                }
              },
              {
                "eventType": "arrival",
                "action": "upsert",
                "fix": {
                  "sec": 40851,
                  "latLng": [
                    33817942,
                    -87266921
                  ]
                }
              }
            ]
          }
        }
      }
    },
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "revision": 113,
      "date": "20151203",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 2918,
          "distanceToNextMt": 73402,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "pickup",
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1"
        },
        {
          "type": "delivery",
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28848,
          "startSec": 28848,
          "endSec": 29748,
          "driveToNextSec": 48,
          "distanceToNextMt": 334,
          "stopIdx": 2,
          "displayLabel": "2.2"
        }
      ],
      "trackingData": {
        "driversTrackingData": {
          "a3935987-4944-462f-b602-4a3a12beeeff": {
            "current": {
              "departure": {
                "sec": 28800,
                "latLng": [
                  33817872,
                  -87266893
                ]
              },
              "arrival": null
            },
            "history": [
              {
                "eventType": "departure",
                "action": "upsert",
                "fix": {
                  "sec": 28800,
                  "latLng": [
                    33817872,
                    -87266893
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "orders": {
    "49269a16-479c-4531-8ffd-513b7ccd0621": {
      "id": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0dd9cab0-d1db-45de-b291-31a0b66d5562": {
      "id": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery(meaning that the Vehicle servicing it will pick up loads at one location and delivered them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    "e2524914-3611-433b-9209-3ee59ee3996e": {
      "id": "e2524914-3611-433b-9209-3ee59ee3996e",
      "name": "Order 6",
      "eligibility": {
        "type": "any",
        "onDates": [
          "20151203"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "deb5a845-40f8-42e0-963e-9646531894a4": {
      "id": "deb5a845-40f8-42e0-963e-9646531894a4",
      "name": "order2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "33.833605,-87.277556",
          "latLng": [
            33833604,
            -87277556
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "idx": 1,
      "externalId": "Vehicle 1",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "009944",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "frozen ton": 500,
            "regular ton": 500
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "frozen",
            "regular"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "frozen ton": 500,
            "regular ton": 500
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "frozen",
            "regular"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    },
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "sameSideOfStreet": false,
      "color": "5500FF",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151205": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "id": "a08213e6-673f-4efc-955e-2bf587813162",
      "name": "Driver 2",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver2@example.com"
    },
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": true,
      "mobileFutureDaysVisibility": 2,
      "email": "driver1@example.com"
    }
  }
}

List current, live Routes, optionally filtering by date and/or vehicleId (synchronous). Route objects contain a sequence of steps that include time-of-arrival data in the form of ETAs (for steps referencing Orders yet to be visited) or Execution Events (as received by the Mobile Application). It also eventually contains route-related tracking data.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/toa/routes[?date=<yyyyMMdd>&vehicle=<vehicleId>]

QUERYSTRING PARAMETERS
Property Type Description
date DateString Optional. If not specified all current (not yet archived) Routes are returned
vehicle UUID Optional. If specified only Routes for the specified Vehicle are returned

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Get Current Route

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203?key=AUTH_KEY&date=20151203

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "routes": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "revision": 113,
      "date": "20151203",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": "",
          "trackingLink": null,
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1",
          "trackingLink": "https://l-nk.io/xZv4ARF",
        },
        {
          "type": "delivery",
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 36135,
          "driveToNextSec": 48,
          "distanceToNextMt": 334,
          "stopIdx": 2,
          "displayLabel": "2.2",
          "trackingLink": null,
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 36183,
          "startSec": 36183,
          "endSec": 36183,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 3,
          "displayLabel": "",
          "trackingLink": null,
        }
      ],
      "trackingData": {
        "driversTrackingData": {
          "a3935987-4944-462f-b602-4a3a12beeeff": {
            "current": {
              "departure": {
                "sec": 28800,
                "latLng": [
                  33817872,
                  -87266893
                ]
              },
              "arrival": null
            },
            "history": [
              {
                "eventType": "departure",
                "action": "upsert",
                "fix": {
                  "sec": 28800,
                  "latLng": [
                    33817872,
                    -87266893
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "orders": {
    "e2524914-3611-433b-9209-3ee59ee3996e": {
      "id": "e2524914-3611-433b-9209-3ee59ee3996e",
      "name": "Order 6",
      "eligibility": {
        "type": "any",
        "onDates": [
          "20151203"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "deb5a845-40f8-42e0-963e-9646531894a4": {
      "id": "deb5a845-40f8-42e0-963e-9646531894a4",
      "name": "order2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "33.833605,-87.277556",
          "latLng": [
            33833604,
            -87277556
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "5500FF",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 600,
          "closeOutTimeSec": 0
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 0,
          "closeOutTimeSec": 0
        },
        "20151205": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 0,
          "closeOutTimeSec": 0
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver1@example.com"
    }
  }
}

Get a current Route (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 6 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/toa/routes/:routeId

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Send Execution Events

Example #1: send time-in, time-out and status events

curl -H "Content-Type: application/json" -X POST -d 'request body #1' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/executionevents?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/executionevents HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "events": [
    {
      "type": "timeIn",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151204",
      "data": {
        "sec": 35132
      }
    },
    {
      "type": "timeOut",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151204",
      "data": {
        "sec": 36875
      }
    },
    {
      "type": "statusUpdate",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151204",
      "data": {
        "sec": 36863,
        "status": "done",
        "statusReason": null
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "a6f01d6b-a085-4812-8784-48d26d888809"
}

And triggers an ExecutionEventsProcessed Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "a6f01d6b-a085-4812-8784-48d26d888809",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "executionEventsProcessed",
  "data": {
    "processed": [
      "OK",
      "OK",
      "OK"
    ]
  }
}

Example #2: send proof-of-delivery events

curl -H "Content-Type: application/json" -X POST -d 'request body #2' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/executionevents?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/toa/executionevents HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "events": [
    {
      "type": "note",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151112",
      "data": {
        "sec": 35203,
        "text": "Best parking spot is 50mt ahead"
      }
    },
    {
      "type": "picture",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151112",
      "data": {
        "id": "picture-1",
        "sec": 35427,
        "text": "Minor damage in lower left corner",
        "mime": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYmICAAAQAAei1PI/AAAAAElFTkSuQmCC"
      }
    },
    {
      "type": "signature",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "orderStepType": "delivery",
      "date": "20151112",
      "data": {
        "id": "customer",
        "sec": 36813,
        "text": "John Black",
        "mime": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYmICAAAQAAei1PI/AAAAAElFTkSuQmCC"
      }
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "303d5b11-23a1-4501-a49c-f26ec2c50094"
}

And triggers an ExecutionEventsProcessed Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "303d5b11-23a1-4501-a49c-f26ec2c50094",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "executionEventsProcessed",
  "data": {
    "processed": [
      "OK",
      "OK",
      "OK"
    ]
  }
}

An Execution Event can be:

An execution event, when processed, causes ETAs of yet-to-be-serviced Orders to be updated.

If time-in data is available but time-out data is not, the time-out time is considered to be the time-in data + the Order’s expected serviceTime. Conversely if time-out data is available but time-in data is not, the time-in time is considered to be the time-out data - the Order’s expected serviceTime.

If both time-in and time-out data is not available but a status-update is present, the time of the status-update is considered as a time-out.

If time-in, time-out and status-update are not available and a proof-of-delivery event is sent, a “done” status-update event is implicitly created at the time reported by the proof-of-delivery event (note: in case “Required Actions for Drivers” feature is enable for the territory, the status-update is not implicitly created)

For each driver, an arrival can be sent only if a departure is already present.

Note: * by default detected time-ins and time-outs do not trigger ETA updates. This behavior can be altered on a per-territory basis. Please contact our support team for more information about this topic. * barcodes proof of deliveries never trigger ETA updates.

THROTTLING

Leaky bucket (size:40, refill: 20 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/toa/executionevents

REQUEST BODY
Property Type Description
events list of ExecutionEvent List of ExecutionEvents to be processed
strict boolean Optional, defaults to true.

When set to true and one or more Events do not pass formal validation checks (e.g.: event referencing a non-existing order or vehicle, a date that is in the past, etc), the request fails and no Events are added. Details about the failed validation are reported in the asynchronous error notification.

When set to false Events that do not pass formal validation checks are skipped without causing the whole request to fail. Skipped events are reported in the ExecutionEventsProcessed Notification
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to executionEventsProcessed
data ExecutionEventsProcessed OR ErrorResponse

Download a Proof of Delivery item

curl https://wwrm.workwave.com/api/v1/pod/20151204-429defc8-ddaa51ee.png?key=AUTH_KEY

GET /pod/20151204-429defc8-ddaa51ee.png HTTP/1.0
Accept: image/png
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

Download a Proof of Delivery item: image or audio recording (synchronous).

THROTTLING

Leaky bucket (size:5, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/pod/:token

QUERYSTRING PARAMETERS
Property Type Description
token String The Proof Of Delivery token provided by Pod objects returned by either “List Current Routes” or “Get Current Route” API requests
RETURN VALUES

(proof of delivery binary data. mime-type available in the content-type header)

Simulations

List Current Routes

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/toa/routes?key=AUTH_KEY&date=20151112

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/toa/routes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "routes": {
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
      "revision": 182,
      "date": "20151204",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "driverId": null,
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 32329,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "delivery",
          "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 34200,
          "startSec": 34200,
          "endSec": 36000,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 1,
          "displayLabel": "1.1"
        },
        {
          "type": "pickup",
          "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 39600,
          "startSec": 39600,
          "endSec": 40600,
          "driveToNextSec": -1,
          "distanceToNextMt": -1,
          "stopIdx": 2,
          "displayLabel": "1.2",
        }
      ],
      "trackingData": null
    },
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "revision": 113,
      "date": "20151203",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": null,
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 2918,
          "distanceToNextMt": 73402,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "pickup",
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1"
        },
        {
          "type": "delivery",
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28848,
          "startSec": 28848,
          "endSec": 29748,
          "driveToNextSec": 48,
          "distanceToNextMt": 334,
          "stopIdx": 2,
          "displayLabel": "2.2"
        }
      ],
      "trackingData": null
    }
  },
  "orders": {
    "49269a16-479c-4531-8ffd-513b7ccd0621": {
      "id": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    },
    "0dd9cab0-d1db-45de-b291-31a0b66d5562": {
      "id": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
      "name": "Order 4",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "frozen ton": 100,
        "regular ton": 300
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "demonstrate the concept of loads. Furthermore this Order involves both a Pickup and a Delivery(meaning that the Vehicle servicing it will pick up loads at one location and delivered them at a different location)",
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1411 Indiana Ave, Jasper, AL 35501, USA",
          "latLng": [
            33836824,
            -87266029
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 52200
          },
          {
            "startSec": 55800,
            "endSec": 59400
          }
        ],
        "notes": "Fragile",
        "serviceTimeSec": 1500,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "Building Entrance Code": "0000"
        }
      },
      "isService": false
    },
    "e2524914-3611-433b-9209-3ee59ee3996e": {
      "id": "e2524914-3611-433b-9209-3ee59ee3996e",
      "name": "Order 6",
      "eligibility": {
        "type": "any",
        "onDates": [
          "20151203"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "deb5a845-40f8-42e0-963e-9646531894a4": {
      "id": "deb5a845-40f8-42e0-963e-9646531894a4",
      "name": "order2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "33.833605,-87.277556",
          "latLng": [
            33833604,
            -87277556
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "idx": 1,
      "externalId": "Vehicle 1",
      "tracked": true,
      "color": "009944",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "frozen ton": 500,
            "regular ton": 500
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "frozen",
            "regular"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "frozen ton": 500,
            "regular ton": 500
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "frozen",
            "regular"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    },
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "color": "5500FF",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        },
        "20151205": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": { }
}

List current, live Routes, optionally filtering by date and/or vehicleId (synchronous). Route objects contain a sequence of steps that include time-of-arrival data in the form of ETAs (for steps referencing Orders yet to be visited) or Execution Events (as received by the Mobile Application). It also eventually contains route-related tracking data.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/toa/routes[?date=<yyyyMMdd>&vehicle=<vehicleId>]

QUERYSTRING PARAMETERS
Property Type Description
date DateString Optional. If not specified all current (not yet archived) Routes are returned
vehicle UUID Optional. If specified only Routes for the specified Vehicle are returned

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Get Current Route

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/toa/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203?key=AUTH_KEY&date=20151203

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/toa/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "routes": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "revision": 113,
      "date": "20151203",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": null,
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": "",
          "trackingLink": null,
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1",
          "trackingLink": "https://l-nk.io/xZv4ARF",
        },
        {
          "type": "delivery",
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 36135,
          "driveToNextSec": 48,
          "distanceToNextMt": 334,
          "stopIdx": 2,
          "displayLabel": "2.2",
          "trackingLink": null,
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 36183,
          "startSec": 36183,
          "endSec": 36183,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 3,
          "displayLabel": "",
          "trackingLink": null,
        }
      ],
      "trackingData": null
    }
  },
  "orders": {
    "e2524914-3611-433b-9209-3ee59ee3996e": {
      "id": "e2524914-3611-433b-9209-3ee59ee3996e",
      "name": "Order 6",
      "eligibility": {
        "type": "any",
        "onDates": [
          "20151203"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "deb5a845-40f8-42e0-963e-9646531894a4": {
      "id": "deb5a845-40f8-42e0-963e-9646531894a4",
      "name": "order2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "33.833605,-87.277556",
          "latLng": [
            33833604,
            -87277556
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "color": "5500FF",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 600,
          "closeOutTimeSec": 0
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 0,
          "closeOutTimeSec": 0
        },
        "20151205": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 0,
          "closeOutTimeSec": 0
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {}
}

Get a current Route (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 6 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/toa/routes/:routeId

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Approved Plans API

List Approved Routes

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes?key=AUTH_KEY&date=20151204

GET /territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "routes": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
      "revision": 166,
      "date": "20151204",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1"
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 35235,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 2,
          "displayLabel": ""
        }
      ]
    },
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
      "revision": 166,
      "date": "20151204",
      "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 32329,
          "driveToNextSec": 360,
          "distanceToNextMt": 2424,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "delivery",
          "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 32689,
          "startSec": 32689,
          "endSec": 33289,
          "driveToNextSec": 3232,
          "distanceToNextMt": 72814,
          "stopIdx": 1,
          "displayLabel": "1.1"
        },
        {
          "type": "delivery",
          "orderId": "65413bab-aea8-41af-8992-487a32f50a59",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 44231,
          "startSec": 44231,
          "endSec": 46031,
          "driveToNextSec": 769,
          "distanceToNextMt": 5955,
          "stopIdx": 2,
          "displayLabel": "1.6"
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 48480,
          "startSec": 48480,
          "endSec": 48480,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 3,
          "displayLabel": ""
        }
      ]
    }
  },
  "orders": {
    "1066ecd2-8171-4daf-a8f3-9bf302a2a38f": {
      "id": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "65413bab-aea8-41af-8992-487a32f50a59": {
      "id": "65413bab-aea8-41af-8992-487a32f50a59",
      "name": "Order 7",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
          "latLng": [
            33843834,
            -87315561
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of tags in/out",
        "serviceTimeSec": 1800,
        "tagsIn": [
          "frozen",
          "regular"
        ],
        "tagsOut": [
          "heavy"
        ],
        "customFields": {}
      },
      "isService": false
    },
    "49269a16-479c-4531-8ffd-513b7ccd0621": {
      "id": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "name": "Order 1",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151204",
          "20151205",
          "20151206"
        ]
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
          "latLng": [
            33817872,
            -87266893
          ],
          "status": "OK"
        },
        "timeWindows": [
          {
            "startSec": 30600,
            "endSec": 37800
          },
          {
            "startSec": 45000,
            "endSec": 55800
          }
        ],
        "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "5500FF",
      "settings": {
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    },
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6": {
      "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
      "idx": 1,
      "externalId": "Vehicle 1",
      "tracked": true,
      "sameSideOfStreet": false,
      "color": "009944",
      "settings": {
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "frozen ton": 500,
            "regular ton": 500
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "frozen",
            "regular"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "id": "a08213e6-673f-4efc-955e-2bf587813162",
      "name": "Driver 2",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver2@example.com"
    },
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": true,
      "mobileFutureDaysVisibility": 31,
      "email": "driver1@example.com"
    }
  }
}

List approved planned Routes (synchronous). Approved Routes define the plan as it was, “frozen” right before being approved for execution, therefore they only contain ETAs.

THROTTLING

Rate-limit (1 call every minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/approved/routes[?date=today|<yyyyMMdd>&dates=<yyyyMMdd>,<yyyyMMdd>]

QUERYSTRING PARAMETERS

Property Type Description
date DateString OR “today” Get all Approved Routes for the given date (defaults to “today”). Note:This input field is deprecated.
dates Comma separated list of DateString Optional. If populated will override the “date” field. Get all Approved Routes for the given dates.

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Get Approved Route

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes/1656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204?key=AUTH_KEY&date=20151204

GET /territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes/1656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "routes": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
      "revision": 166,
      "date": "20151204",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1"
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 35235,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 2,
          "displayLabel": ""
        }
      ]
    }
  },
  "orders": {
    "1066ecd2-8171-4daf-a8f3-9bf302a2a38f": {
      "id": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    }
  },
  "vehicles": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "color": "5500FF",
      "settings": {
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": true,
      "mobileFutureDaysVisibility": 31,
      "email": "driver1@example.com"
    }
  }
}

Get an approved planned Route (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 6 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/approved/routes/:routeId

RETURN VALUES

Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

Approve Routes

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/20151204?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/20151204 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "requestId": "cf65a452-68be-4ffa-a8e6-25a2b80466b4"
}

And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "cf65a452-68be-4ffa-a8e6-25a2b80466b4",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "approved": ["20151204"],
    "revoked": []
  }
}

Approve (or update approval of) all Routes for the given date (asynchronous).

Approving Routes:

THROTTLING

Leaky bucket (size:3, refill: 1 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/approved/:date

QUERYSTRING PARAMETERS

Property Type Description
date DateString The date where Routes must be approved

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to approvedRoutesChanged
data ApprovedRoutesChanged OR ErrorResponse The list of dates where Routes have been approved, or where approval has been updated

Revoke Routes

curl -H "Content-Type: application/json" -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/20151205?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/20151205 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "requestId": "30eef241-ca63-4d6f-94a2-97352a7a1393"
}

And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "30eef241-ca63-4d6f-94a2-97352a7a1393",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "revoked": ["20151205"]
  }
}

Revoke approval for all Routes for the given date (asynchronous).

THROTTLING

Leaky bucket (size:3, refill: 1 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/approved/:date

QUERYSTRING PARAMETERS

Property Type Description
date DateString The date where Routes must be revoked approval

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to approvedRoutesChanged
data ApprovedRoutesChanged OR ErrorResponse The list of dates where Routes have been revoked approval

Approved Plans API v2

Why v2 for Approved Plans

Compared to v1 that only allows approving/revoking routes for a whole day, v2 methods allow finer-grained per-route approval/revocation.

Under normal circumstances this new functionality could have been achieved by simply adding appropriate filters to the Approve and Revoke Routes methods, preserving backward compatibility and avoiding a new version.

Unfortunately, the data format returned by List and Get Planned Routes had to be changed in a non-backward compatible way to take into account some scenarios, enabled by independently approving Routes belonging to the same date, that were not previously possible.

Consider the following scenario:

  1. Approve Route R1_1 (let’s call it so for reference’s sake) run by Vehicle V1 on date D1, servicing an Order O1 with a service time of 10 minutes
  2. After approving Route R1_1, remove Order O1 from Route R1_1 manually re-assigning it to another not-yet-approved Route R2_1 run by Vehicle V2 also on Date D1
  3. Update Order O1 increasing its service time to 30 minutes
  4. Now approve Route R2_1

If, in the above scenario, approved Routes are listed, they would include two Routes (R1_1 and R2_1), for the same day (D1), referencing the same Order (O1) where, however, O1-planned-on-R1_1 has a service time of 10 minutes while O1-planned-on-R2_1 has a service time of 30 minutes.

The result format returned by v1’s List Approved Routes cannot account for that (since the two “versions” of O1, approved on different Routes at different times, still have the same ID, only one version can be referenced), which is why v2 was introduced.

While this might seem, and probably is, an edge-case, it is allowed by the system for maximum flexibility’s sake (freedom of re-assigning Orders at all times and under all circumstances), and therefore it must be accounted for in the result format.

Compatibility with v1

v1 methods will continue to work as before, with one attention point in case the plan happens to be in the above described state: the data returned by v1’s List Approved Routes will include two Routes both referencing Order O1, but include only one version of O1 (which one of the two is undetermined).

v1’s Get Approved Route, since it returns data for one single Route at a time, will always return the correct Order data (that is: Get Approved Route for R1_1 will include the 10 min version of O1 and Get Approved Route for R2_1 the 30 min version).

v1’s Approve and Revoke Routes methods will continue to respectively approve and revoke all Routes for the given date.

List Approved Routes v2

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes?key=AUTH_KEY&date=20151204

GET /territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "approvedRoutes": [
    {
      "route": {
        "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
        "revision": 166,
        "date": "20151204",
        "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
        "steps": [
          {
            "type": "departure",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 0,
            "startSec": 0,
            "endSec": 28800,
            "driveToNextSec": 0,
            "distanceToNextMt": 0,
            "stopIdx": 0,
            "displayLabel": ""
          },
          {
            "type": "preparation",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 28800,
            "startSec": 28800,
            "endSec": 29400,
            "driveToNextSec": 2318,
            "distanceToNextMt": 73402,
            "stopIdx": -1
          },
          {
            "type": "pickup",
            "orderId": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 31718,
            "startSec": 31718,
            "endSec": 32318,
            "driveToNextSec": 2917,
            "distanceToNextMt": 73549,
            "stopIdx": 1,
            "displayLabel": "2.1"
          },
          {
            "type": "arrival",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 35235,
            "startSec": 35235,
            "endSec": 35235,
            "driveToNextSec": 0,
            "distanceToNextMt": 0,
            "stopIdx": 2,
            "displayLabel": ""
          }
        ]
      },
      "vehicle": {
        "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "idx": 2,
        "externalId": "Vehicle 2",
        "tracked": true,
        "sameSideOfStreet": true,
        "settings": {
          "20151204": {
            "available": true,
            "notes": "",
            "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "timeWindow": {
              "startSec": 28800,
              "endSec": 61200
            },
            "flexStartTime": true,
            "perStopCost": 0,
            "perStopTimeSec": 0,
            "maxWorkingTimeSec": 0,
            "maxDrivingTimeSec": 0,
            "maxDistanceMt": 0,
            "maxOrders": 0,
            "maxLocations": 0,
            "maxStops": 0,
            "breaks": [],
            "loadCapacities": {
              "people": 600
            },
            "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
            "activationCost": 0,
            "drivingTimeCost": 2000,
            "idleTimeCost": 2000,
            "serviceTimeCost": 2000,
            "breakTimeCost": 2000,
            "kmCost": 100,
            "tags": [
              "heavy"
            ],
            "speedFactor": 100,
            "minWorkingTimeSec": 0,
            "minLoadCapacities": {}
          }
        }
      },
      "driver": {
        "id": "a3935987-4944-462f-b602-4a3a12beeeff",
        "name": "Driver 1",
        "summarizeFutureMobileRoute": false,
        "mobileFutureDaysVisibility": 2,
        "email": "driver1@example.com"
      },
      "orders": {
        "1066ecd2-8171-4daf-a8f3-9bf302a2a38f": {
          "id": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
          "name": "Order 6",
          "eligibility": {
            "type": "any"
          },
          "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
          "priority": 0,
          "loads": {
            "people": 400
          },
          "pickup": {
            "depotId": null,
            "location": {
              "address": "",
              "latLng": [
                33480873,
                -86788220
              ],
              "status": "OK"
            },
            "timeWindows": [],
            "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
            "serviceTimeSec": 600,
            "tagsIn": [],
            "tagsOut": [],
            "customFields": {}
          },
          "delivery": null,
          "isService": false
        }
      },
      "depots": {
        "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
          "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "name": "TEST",
          "setupCost": -1,
          "setupTimeSec": -1,
          "location": {
            "address": "320 20th St W, Jasper, AL 35501, USA",
            "latLng": [
              33831316,
              -87278355
            ],
            "status": "OK"
          },
          "color": "998800"
        }
      }
    },
    {
      "route": {
        "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
        "revision": 166,
        "date": "20151204",
        "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
        "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
        "steps": [
          {
            "type": "departure",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 0,
            "startSec": 0,
            "endSec": 32329,
            "driveToNextSec": 360,
            "distanceToNextMt": 2424,
            "displayLabel": ""
          },
          {
            "type": "delivery",
            "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 32689,
            "startSec": 32689,
            "endSec": 33289,
            "driveToNextSec": 3232,
            "distanceToNextMt": 72814,
            "displayLabel": "1.1"
          },
          {
            "type": "delivery",
            "orderId": "65413bab-aea8-41af-8992-487a32f50a59",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 44231,
            "startSec": 44231,
            "endSec": 46031,
            "driveToNextSec": 769,
            "distanceToNextMt": 5955,
            "displayLabel": "1.6"
          },
          {
            "type": "arrival",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 48480,
            "startSec": 48480,
            "endSec": 48480,
            "driveToNextSec": 0,
            "distanceToNextMt": 0,
            "displayLabel": ""
          }
        ]
      },
      "vehicle": {
        "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
        "idx": 1,
        "externalId": "Vehicle 1",
        "tracked": true,
        "sameSideOfStreet": false,
        "settings": {
          "20151204": {
            "available": true,
            "notes": "",
            "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "timeWindow": {
              "startSec": 28800,
              "endSec": 61200
            },
            "flexStartTime": true,
            "perStopCost": 0,
            "perStopTimeSec": 0,
            "maxWorkingTimeSec": 0,
            "maxDrivingTimeSec": 0,
            "maxDistanceMt": 0,
            "maxOrders": 0,
            "maxLocations": 0,
            "maxStops": 0,
            "breaks": [],
            "loadCapacities": {
              "frozen ton": 500,
              "regular ton": 500
            },
            "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
            "activationCost": 0,
            "drivingTimeCost": 2000,
            "idleTimeCost": 2000,
            "serviceTimeCost": 2000,
            "breakTimeCost": 2000,
            "kmCost": 100,
            "tags": [
              "frozen",
              "regular"
            ],
            "speedFactor": 100,
            "minWorkingTimeSec": 0,
            "minLoadCapacities": {}
          }
        }
      },
      "driver": {
        "id": "a08213e6-673f-4efc-955e-2bf587813162",
        "name": "Driver 2",
        "summarizeFutureMobileRoute": false,
        "mobileFutureDaysVisibility": 2,
        "email": "driver2@example.com"
      },
      "orders": {
        "65413bab-aea8-41af-8992-487a32f50a59": {
          "id": "65413bab-aea8-41af-8992-487a32f50a59",
          "name": "Order 7",
          "eligibility": {
            "type": "on",
            "onDates": [
              "20151204"
            ]
          },
          "forceVehicleId": null,
          "priority": 0,
          "loads": {},
          "pickup": null,
          "delivery": {
            "depotId": null,
            "location": {
              "address": "1300 S Skyline Dr, Jasper, AL 35501, USA",
              "latLng": [
                33843834,
                -87315561
              ],
              "status": "OK"
            },
            "timeWindows": [],
            "notes": "Demonstrate the concept of tags in/out",
            "serviceTimeSec": 1800,
            "tagsIn": [
              "frozen",
              "regular"
            ],
            "tagsOut": [
              "heavy"
            ],
            "customFields": {}
          },
          "isService": false
        },
        "49269a16-479c-4531-8ffd-513b7ccd0621": {
          "id": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "name": "Order 1",
          "eligibility": {
            "type": "on",
            "onDates": [
              "20151204",
              "20151205",
              "20151206"
            ]
          },
          "forceVehicleId": null,
          "priority": 0,
          "loads": {},
          "pickup": null,
          "delivery": {
            "depotId": null,
            "location": {
              "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
              "latLng": [
                33817872,
                -87266893
              ],
              "status": "OK"
            },
            "timeWindows": [
              {
                "startSec": 30600,
                "endSec": 37800
              },
              {
                "startSec": 45000,
                "endSec": 55800
              }
            ],
            "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
            "serviceTimeSec": 600,
            "tagsIn": [],
            "tagsOut": [],
            "customFields": {}
          },
          "isService": false
        }
      },
      "depots": {
        "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
          "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "name": "TEST",
          "setupCost": -1,
          "setupTimeSec": -1,
          "location": {
            "address": "320 20th St W, Jasper, AL 35501, USA",
            "latLng": [
              33831316,
              -87278355
            ],
            "status": "OK"
          },
          "color": "998800"
        }
      }
    }
  ]
}

List approved planned Routes (synchronous).

Approved Routes define routes as they where, “frozen” at the time of their approval for execution, therefore they only contain ETAs.

They serve as a “snapshot” of how the Route had originally been planned and how it was supposed to be executed, to be used as reference and/or to be compared with the actual, executed-in-the-real-world version of the same Route.

An approved Route can be revoked or updated and re-approved, up until an Execution Event (time-in, time-out, etc) is captured by the system about an Order serviced by the Route. At that point it is not possible to revoke or update the approved Route anymore.

THROTTLING

Rate-limit (1 call every minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v2/territories/:territoryId/approved/routes[?date=today|<yyyyMMdd>&dates=<yyyyMMdd>,<yyyyMMdd>]

QUERYSTRING PARAMETERS

Property Type Description
date DateString OR “today” Get all Approved Routes for the given date (defaults to “today”). Note:This input field is deprecated.
dates Comma separated list of DateString Optional. If populated will override the “date” field. Get all Approved Routes for the given dates.

RETURN VALUES

Property Type Description
approvedRoutes list of ApprovedRoute A list of ApprovedRoute

Get Approved Route v2

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204?key=AUTH_KEY&date=20151204

GET /territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved/routes/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  {
    "route": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
      "revision": 166,
      "date": "20151204",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": "2.1"
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 35235,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 2,
          "displayLabel": ""
        }
      ]
    },
    "vehicle": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "settings": {
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "maxLocations": 0,
          "maxStops": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    },
    "driver": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver1@example.com"
    },
    "orders": {
      "1066ecd2-8171-4daf-a8f3-9bf302a2a38f": {
        "id": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
        "name": "Order 6",
        "eligibility": {
          "type": "any"
        },
        "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "priority": 0,
        "loads": {
          "people": 400
        },
        "pickup": {
          "depotId": null,
          "location": {
            "address": "",
            "latLng": [
              33480873,
              -86788220
            ],
            "status": "OK"
          },
          "timeWindows": [],
          "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
          "serviceTimeSec": 600,
          "tagsIn": [],
          "tagsOut": [],
          "customFields": {}
        },
        "delivery": null,
        "isService": false
      }
    },
    "depots": {
      "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
        "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "name": "TEST",
        "setupCost": -1,
        "setupTimeSec": -1,
        "location": {
          "address": "320 20th St W, Jasper, AL 35501, USA",
          "latLng": [
            33831316,
            -87278355
          ],
          "status": "OK"
        },
        "color": "998800"
      }
    }
  }
}

Get an approved planned Route (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 6 per minute)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v2/territories/:territoryId/approved/routes/:routeId

RETURN VALUES

ApprovedRoute Object

Approve Routes v2

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

{
  "ids": [
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151205"
  ],
  "strict": false
}

The above command returns JSON structured like this:

{
  "requestId": "761ce1c6-3336-4e00-8296-5d1885b0ad4d"
}

And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "761ce1c6-3336-4e00-8296-5d1885b0ad4d",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "approved": ["20151204", "20151205"],
    "revoked": []
  }
}

Approve (or update approval of) the given Routes (asynchronous).

Approving Routes:

THROTTLING

Leaky bucket (size:3, refill: 1 per minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v2/territories/:territoryId/approved

REQUEST BODY

Property Type Description
ids list of String List of routeIds to be approved.
Note: approving an empty Route is the same as revoking its approval.
Note: unless strict is set to false, a routeId that is malformed, or referencing a non-existing vehicle, or a date further than the allowed horizon, or a Route that is being executed, or a Route whose approval would exceed the limits, causes the request to fail.
LIMITS: excluding dates in the past and today, there can be only 3 future dates with one or more approved Routes. Approving one or more Routes on a 4th future date causes the request to fail (unless strict is false, in which case routeIds referencing dates in excess of the limit are ignored).
strict boolean Optional, defaults to true. When set to false causes invalid routeIds to be silently ignored without making the request fail

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to approvedRoutesChanged
data ApprovedRoutesChanged OR ErrorResponse The list of dates where Routes have been approved, or where approval has been updated

Revoke Routes v2

curl -H "Content-Type: application/json" -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

{
  "ids": [
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151205"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82"
}

And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:

// If after revoking the given routeIds there are no more approved Routes on 2015-12-05:
{
  "requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "revoked": ["20151205"]
  }
}

// If after revoking the given routeIds there is still one or more approved Routes on 2015-12-05,
// and to indicate that the approval status of Routes for 2015-12-05 changed:
{
  "requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "approved": ["20151205"]
  }
}

Revoke approval for the given Routes (asynchronous).

THROTTLING

Leaky bucket (size:3, refill: 1 per minute)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v2/territories/:territoryId/approved

REQUEST BODY

Property Type Description
ids list of String List of routeIds whose approval must be revoked.
Note: invalid routeIds are ignored

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to approvedRoutesChanged
data ApprovedRoutesChanged OR ErrorResponse The list of dates where Routes have been revoked approval

Scheduling API

Operations

Build Routes

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/buildroutes?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/buildroutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "from": "20151204",
  "to": "20151207"
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

(Re)build Routes with the goal of serving all Orders eligible in the given date-range minimizing the overall cost (asynchronous).

The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Full Optimization” option.

THROTTLING

Rate-limit (1 call every 1 minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/buildroutes

REQUEST BODY
Property Type Description
from DateString Inclusive
to DateString Inclusive. Must be >= from. Must not exceed the allowed optimization horizon.
lockedRouteIdsOverride list of String Optional list of routeIds. Defaults to null.
If null UI-defined locks are honored.
If not null UI-defined locks are ignored and replaced with those from this list. The scope of the override is limited to the request (UI-defined locks are left unchanged)
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Fit-In Unassigned Orders

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/fitin?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/fitin HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "from": "20151204",
  "to": "20151204",
  "orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"],
  "includeRoutesWithViolations": "none"
}

The above command returns JSON structured like this:

{
  "requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"],
    "outOfBorderOrderIds": ["3419b8f6-1767-4710-be3e-14d4ff614b57"]
  }
}

Fit unassigned Orders into Routes in the given date-range minimizing the overall cost and preserving existing Vehicle-Route assignments (asynchronous).

The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Fit In unassigned Orders” option.

If Orders cannot be fit into existing routes but unused Vehicles are available, they will be used.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/fitin

REQUEST BODY
Property Type Description
from DateString Inclusive
to DateString Inclusive. Must be >= from. Must not exceed the allowed optimization horizon
orderIds list of String Optional. Ids of eligible, unassigned Orders that should be fitted in. If null or empty the system will try to fit-in all unassigned Orders that are eligible in the given date range
routeIds list of String Optional. If provided, the system tries to fit Orders only in the given Routes. If null or empty the system will try to fit Orders in any available Route (existing or new) matching the given from/to date range. If specified overrides from/to preperties.
overrideLockedRoutes boolean Optional. Defaults to false.
If set to false UI-defined locks are honored.
If set to true UI-defined locks are ignored (i.e.: all Routes and Vehicles matched by the date range and by routeIds become eligible targets for fitting in unassigned Orders regardless of UI-defined locks)
includeRoutesWithViolations enum One of none or vehicleOrderAssignment.
Optional. Defaults to none.
If set to none existing Routes that violate one or more constraints are excluded from the list of eligible fit-in targets.
If set to vehicleOrderAssignment existing Routes where already-assigned Orders violate one or more of the following constraints are considered eligible fit-in targets: tag, region, date eligibility, forced vehicle assignment.
Note: selecting this option still ensures that no additional violations are generated (i.e.: unassigned Orders that are fit-in to some Route as a result of this this request will not violate any constraint)
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Unassign Orders [Deprecated]

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderIds": [
    "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
    "16836b9f-f059-4520-8554-74eeb63e5797"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
     {
        "orderId": "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
        "type": "delivery"
      },
      {
        "orderId": "16836b9f-f059-4520-8554-74eeb63e5797",
        "type": "delivery"
      }
    ]
  }
}

Unassign Orders from their current routes, clearing their tracking data (asynchronous).

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/unassign[?orderIds=<comma_separated_list>]

REQUEST BODY
Property Type Description
orderIds list of String Mandatory. List of one or more Orders to unassign.
QUERYSTRING PARAMETERS
Property Type Description
orderIds comma-separated list of String Mandatory. List of one or more Orders to unassign.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data UnassignOrderList OR ErrorResponse

Assign an OrderStep

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f"
}

And, if the OrderStep is successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      }
    ]
  }
}

Or, if the OrderStep could not be (re)assigned, like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
    ]
  }
}

Assign an OrderStep to the given Route at the given position in time, updating ETAs accordingly (asynchronous).

If the OrderStep is presently assigned to a different Route, ETAs for both involved Routes are updated.

Note: It is not allowed to assign an OrderStep to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/assign/:orderId/:orderStepType/to/:routeId/after/:sec

PATH PARAMETERS
Property Type Description
orderId UUID Identifies the Order
orderStepType enum Identifies the OrderStep. Can be pickup or delivery
routeId String Mandatory. Identifies the target Route. A target Route is created if it does not already exist. For the correct format of this field, refer to the id field of the Route Object definition.
sec int The time, in seconds since midnight, after which the OrderStep should be positioned. Set it to 0 to assign the OrderStep at the beginning of the Route.
Note: The system uses the provided time to figure out where, in the current sequence, the OrderStep needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderStep is scheduled might end up being different.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Assign Multiple OrderSteps

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderSteps": [
    {
      "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "type": "delivery"
    },
    {
      "orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
      "type": "delivery"
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e"
}

And, if OrderSteps are successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      },
      {
        "orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
        "type": "delivery"
      }
    ]
  }
}

Or, if the OrderSteps could not be (re)assigned, like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
    ]
  }
}

Assign one or more unassigned OrderSteps to the given Route starting at the given position in time, updating ETAs accordingly (asynchronous).

Limitations:: contrary to the single (re)assignment method, none of the referenced OrderSteps can be already assigned to existing Routes, therefore this method cannot be used to move/reassign OrderSteps from one Route to another.

Note: It is not allowed to assign OrderSteps to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.

THROTTLING

Leaky bucket (size:10, refill: 1 per 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/assign/to/:routeId/after/:sec

PATH PARAMETERS
Property Type Description
routeId String Mandatory. Identifies the target Route. A target Route is created if it does not already exist. For the correct format of this field, refer to the id field of the Route Object definition.
sec int The time, in seconds since midnight, after which the list of OrderSteps should be positioned. Set it to 0 to assign the OrderSteps at the beginning of the Route.
Note: The system uses the provided time to figure out where, in the current sequence, the list of OrderSteps needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderSteps are scheduled might end up being different.
REQUEST BODY
Property Type Description
orderSteps list of OrderStepIdentifier Mandatory. List of one or more OrderSteps to be assigned to the target route at the given time (and in the given sequence).
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Apply Sequences

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/applysequences?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/applysequences HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "sequences": [
    {
      "routeId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151207",
      "orderSteps": [
        {
          "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "type": "delivery"
        },
        {
          "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
          "type": "pickup"
        }
      ]
    },
    {
      "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151207",
      "orderSteps": [
        {
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "type": "pickup"
        },
        {
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "type": "delivery"
        }
      ]
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "28193dc3-557a-4b41-b122-7b97c7e72992"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "28193dc3-557a-4b41-b122-7b97c7e72992",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

Create new Routes based on the given sequences of OrderSteps (asynchronous).

Contrary to Build Routes no optimization is involved and the system strictly honors the given sequences limiting its role to computing ETAs based on estimated driving times and attempting to limit time-constraints violations (like Orders’ Time Windows) where possible.

This method is somewhat similar to Assign Multiple OrderSteps but differs from it in that it can create multiple Routes with one single request, but new Routes only, it does not allow assigning to existing Routes.

As with the multiple assignment method none of the referenced OrderSteps can be already assigned to existing Routes, therefore it cannot be used to move/reassign OrderSteps from one Route to another.

THROTTLING

Rate-limit (1 call every 60 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/applysequences

REQUEST BODY
Property Type Description
sequences list of RouteSequence Mandatory. List of one or more Sequences.
LIMITS: Routes referenced by RouteSequence objects MUST be empty, and listed OrderSteps MUST NOT be already assigned to existing Routes
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Swap Routes

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/swaproutes?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/swaproutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "srcRouteId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
  "dstRouteId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0-20151203"
}

The above command returns JSON structured like this:

{
  "requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

Swap the orderstep sequences between two routes, moving the sequence of the first route on the second one and vice versa (asynchronous).

The behavior is equivalent to the “Swap” functionality of the WorkWave Route Manager Web Application.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/swaproutes

REQUEST BODY
Property Type Description
srcRouteId String routeId of the first route included within the process
dstRouteId String routeId of the second route included within the process
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Get Progress

curl -H "Content-Type: application/json" -X GET -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/progress?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/progress HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "progress": 75
}

Returns the progress of a “Build Routes” ot “Fit-in” optimization currently running in a territory. If there are no running optimizations for the given territory it will respond with a 404 status (even if there is an optimization queued). The optimization could have been started either via API or from the UI.

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/progress

RETURN VALUES
Property Type Description
progress int Optimization progress percentage (0 - 100)

Sequential Fit

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/7266d500-6246-48b6-890a-761bd5c60909/scheduling/experimental/sequentialfit?key=AUTH_KEY

POST /api/v1/territories/7266d500-6246-48b6-890a-761bd5c60909/scheduling/experimental/sequentialfit HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json


{
  "orderSteps": [
    {
      "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
      "type": "delivery"
    },
    {
      "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
      "type": "pickup"
    }
  ],
  "dstRouteId": "cb1c9af3-dc1c-4749-8530-0c89f1b0aac6-20241113"
}

The above command returns JSON structured like this:

{
  "requestId": "9966d500-6246-48b6-890a-761bd5c60909"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9966d500-6246-48b6-890a-761bd5c60909",
  "territoryId": "7266d500-6246-48b6-890a-761bd5c60909",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
        "type": "delivery"
      },
      {
        "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
        "type": "pickup"
      }
    ]
  }
}


The process involves fetching each orderstep sequentially from the input list and inserting it into the sequence of the ordersteps already scheduled within the route, attempting to find the best position for it. It is ensured that the existing ordersteps sequence remains unchanged.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/experimental/sequentialfit

REQUEST BODY
Property Type Description
orderSteps list of OrderStepIdentifier Mandatory. List of one or more OrderSteps to be assigned to the target route.
dstRouteId String Target routeId.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Simulations

Build Routes

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/buildroutes?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/buildroutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "from": "20151204",
  "to": "20151207"
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

(Re)build Routes with the goal of serving all Orders eligible in the given date-range minimizing the overall cost (asynchronous).

The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Full Optimization” option.

THROTTLING

Rate-limit (1 call every 1 minute)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/buildroutes

REQUEST BODY
Property Type Description
from DateString Inclusive
to DateString Inclusive. Must be >= from. Must not exceed the allowed optimization horizon.
lockedRouteIdsOverride list of String Optional list of routeIds. Defaults to null.
If null UI-defined locks are honored.
If not null UI-defined locks are ignored and replaced with those from this list. The scope of the override is limited to the request (UI-defined locks are left unchanged)
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Fit-In Unassigned Orders

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/fitin?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/fitin HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "from": "20151204",
  "to": "20151204",
  "orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"],
  "includeRoutesWithViolations": "none"
}

The above command returns JSON structured like this:

{
  "requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"],
    "outOfBorderOrderIds": ["3419b8f6-1767-4710-be3e-14d4ff614b57"]
  }
}

Fit unassigned Orders into Routes in the given date-range minimizing the overall cost and preserving existing Vehicle-Route assignments (asynchronous).

The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Fit In unassigned Orders” option.

If Orders cannot be fit into existing routes but unused Vehicles are available, they will be used.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/fitin

REQUEST BODY
Property Type Description
from DateString Inclusive
to DateString Inclusive. Must be >= from. Must not exceed the allowed optimization horizon
orderIds list of String Optional. Ids of eligible, unassigned Orders that should be fitted in. If null or empty the system will try to fit-in all unassigned Orders that are eligible in the given date range
routeIds list of String Optional. If provided, the system tries to fit Orders only in the given Routes. If null or empty the system will try to fit Orders in any available Route (existing or new) matching the given from/to date range. If specified overrides from/to preperties.
overrideLockedRoutes boolean Optional. Defaults to false.
If set to false UI-defined locks are honored.
If set to true UI-defined locks are ignored (i.e.: all Routes and Vehicles matched by the date range and by routeIds become eligible targets for fitting in unassigned Orders regardless of UI-defined locks)
includeRoutesWithViolations enum One of none or vehicleOrderAssignment.
Optional. Defaults to none.
If set to none existing Routes that violate one or more constraints are excluded from the list of eligible fit-in targets.
If set to vehicleOrderAssignment existing Routes where already-assigned Orders violate one or more of the following constraints are considered eligible fit-in targets: tag, region, date eligibility, forced vehicle assignment.
Note: selecting this option still ensures that no additional violations are generated (i.e.: unassigned Orders that are fit-in to some Route as a result of this this request will not violate any constraint)
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Unassign Orders [Deprecated]

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/unassign?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderIds": [
    "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
    "16836b9f-f059-4520-8554-74eeb63e5797"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
     {
        "orderId": "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
        "type": "delivery"
      },
      {
        "orderId": "16836b9f-f059-4520-8554-74eeb63e5797",
        "type": "delivery"
      }
    ]
  }
}

Unassign Orders from their current routes, clearing their tracking data (asynchronous).

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/unassign[?orderIds=<comma_separated_list>]

REQUEST BODY
Property Type Description
orderIds list of String Mandatory. List of one or more Orders to unassign.
QUERYSTRING PARAMETERS
Property Type Description
orderIds comma-separated list of String Mandatory. List of one or more Orders to unassign.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data UnassignOrderList OR ErrorResponse

Assign an OrderStep

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f"
}

And, if the OrderStep is successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      }
    ]
  }
}

Or, if the OrderStep could not be (re)assigned, like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
    ]
  }
}

Assign an OrderStep to the given Route at the given position in time, updating ETAs accordingly (asynchronous).

If the OrderStep is presently assigned to a different Route, ETAs for both involved Routes are updated.

Note: It is not allowed to assign an OrderStep to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/assign/:orderId/:orderStepType/to/:routeId/after/:sec

PATH PARAMETERS
Property Type Description
orderId UUID Identifies the Order
orderStepType enum Identifies the OrderStep. Can be pickup or delivery
routeId String Mandatory. Identifies the target Route. A target Route is created if it does not already exist. For the correct format of this field, refer to the id field of the Route Object definition.
sec int The time, in seconds since midnight, after which the OrderStep should be positioned. Set it to 0 to assign the OrderStep at the beginning of the Route.
Note: The system uses the provided time to figure out where, in the current sequence, the OrderStep needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderStep is scheduled might end up being different.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Assign Multiple OrderSteps

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderSteps": [
    {
      "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "type": "delivery"
    },
    {
      "orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
      "type": "delivery"
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e"
}

And, if OrderSteps are successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      },
      {
        "orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
        "type": "delivery"
      }
    ]
  }
}

Or, if the OrderSteps could not be (re)assigned, like this:

{
  "requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
    ]
  }
}

Assign one or more unassigned OrderSteps to the given Route starting at the given position in time, updating ETAs accordingly (asynchronous).

Limitations:: contrary to the single (re)assignment method, none of the referenced OrderSteps can be already assigned to existing Routes, therefore this method cannot be used to move/reassign OrderSteps from one Route to another.

Note: It is not allowed to assign OrderSteps to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.

THROTTLING

Leaky bucket (size:10, refill: 1 per 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/assign/to/:routeId/after/:sec

PATH PARAMETERS
Property Type Description
routeId String Mandatory. Identifies the target Route. A target Route is created if it does not already exist. For the correct format of this field, refer to the id field of the Route Object definition.
sec int The time, in seconds since midnight, after which the list of OrderSteps should be positioned. Set it to 0 to assign the OrderSteps at the beginning of the Route.
Note: The system uses the provided time to figure out where, in the current sequence, the list of OrderSteps needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderSteps are scheduled might end up being different.
REQUEST BODY
Property Type Description
orderSteps list of OrderStepIdentifier Mandatory. List of one or more OrderSteps to be assigned to the target route at the given time (and in the given sequence).
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Apply Sequences

curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/applysequences?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/applysequences HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "sequences": [
    {
      "routeId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151207",
      "orderSteps": [
        {
          "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
          "type": "delivery"
        },
        {
          "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
          "type": "pickup"
        }
      ]
    },
    {
      "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151207",
      "orderSteps": [
        {
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "type": "pickup"
        },
        {
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "type": "delivery"
        }
      ]
    }
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "28193dc3-557a-4b41-b122-7b97c7e72992"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "28193dc3-557a-4b41-b122-7b97c7e72992",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

Create new Routes based on the given sequences of OrderSteps (asynchronous).

Contrary to Build Routes no optimization is involved and the system strictly honors the given sequences limiting its role to computing ETAs based on estimated driving times and attempting to limit time-constraints violations (like Orders’ Time Windows) where possible.

This method is somewhat similar to Assign Multiple OrderSteps but differs from it in that it can create multiple Routes with one single request, but new Routes only, it does not allow assigning to existing Routes.

As with the multiple assignment method none of the referenced OrderSteps can be already assigned to existing Routes, therefore it cannot be used to move/reassign OrderSteps from one Route to another.

THROTTLING

Rate-limit (1 call every 60 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/applysequences

REQUEST BODY
Property Type Description
sequences list of RouteSequence Mandatory. List of one or more Sequences.
LIMITS: Routes referenced by RouteSequence objects MUST be empty, and listed OrderSteps MUST NOT be already assigned to existing Routes
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Swap Routes

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/swaproutes?key=AUTH_KEY

POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/swaproutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "srcRouteId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
  "dstRouteId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0-20151203"
}

The above command returns JSON structured like this:

{
  "requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

Swap the orderstep sequences between two routes, moving the sequence of the first route on the second one and vice versa (asynchronous).

The behavior is equivalent to the “Swap” functionality of the WorkWave Route Manager Web Application.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/swaproutes

REQUEST BODY
Property Type Description
srcRouteId String routeId of the first route included within the process
dstRouteId String routeId of the second route included within the process
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Get Progress

curl -H "Content-Type: application/json" -X GET -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/progress?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/progress HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "progress": 75
}

Returns the progress of a “Build Routes” ot “Fit-in” optimization currently running in a territory. If there are no running optimizations for the given territory it will respond with a 404 status (even if there is an optimization queued). The optimization could have been started either via API or from the UI.

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/progress

RETURN VALUES
Property Type Description
progress int Optimization progress percentage (0 - 100)

Sequential Fit

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/7266d500-6246-48b6-890a-761bd5c60909/scheduling/experimental/sequentialfit?key=AUTH_KEY

POST /api/v1/territories/7266d500-6246-48b6-890a-761bd5c60909/scheduling/experimental/sequentialfit HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json


{
  "orderSteps": [
    {
      "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
      "type": "delivery"
    },
    {
      "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
      "type": "pickup"
    }
  ],
  "dstRouteId": "cb1c9af3-dc1c-4749-8530-0c89f1b0aac6-20241113"
}

The above command returns JSON structured like this:

{
  "requestId": "9966d500-6246-48b6-890a-761bd5c60909"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "9966d500-6246-48b6-890a-761bd5c60909",
  "territoryId": "7266d500-6246-48b6-890a-761bd5c60909",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
        "type": "delivery"
      },
      {
        "orderId": "1394db69-058a-42e8-8be5-5e9d1da5d83c",
        "type": "pickup"
      }
    ]
  }
}


The process involves fetching each orderstep sequentially from the input list and inserting it into the sequence of the ordersteps already scheduled within the route, attempting to find the best position for it. It is ensured that the existing ordersteps sequence remains unchanged.

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/simulation/:simulationId/scheduling/experimental/sequentialfit

REQUEST BODY
Property Type Description
orderSteps list of OrderStepIdentifier Mandatory. List of one or more OrderSteps to be assigned to the target route.
dstRouteId String Target routeId.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Scheduling API v2

Operations

Unassign Orders v2

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v2/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderIds": [
    "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
    "16836b9f-f059-4520-8554-74eeb63e5797"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
      "603a348f-7fcc-4bdc-8f4a-ec10a68547e0", 
      "16836b9f-f059-4520-8554-74eeb63e5797"
    ]
  }
}

Unassign Orders from their current routes, clearing their tracking data (asynchronous).

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v2/territories/:territoryId/scheduling/unassign[?orderIds=<comma_separated_list>]

REQUEST BODY
Property Type Description
orderIds list of String Mandatory. List of one or more Orders to unassign.
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
orderIds comma-separated list of String Mandatory. List of one or more Orders to unassign.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Simulations

Unassign Orders v2

curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v2/territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/unassign?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/simulation/ccb66278-c870-41ea-9741-f3f1159b10b8/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "orderIds": [
    "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
    "16836b9f-f059-4520-8554-74eeb63e5797"
  ]
}

The above command returns JSON structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}

And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
  "simulationId": "ccb66278-c870-41ea-9741-f3f1159b10b8",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
      "603a348f-7fcc-4bdc-8f4a-ec10a68547e0", 
      "16836b9f-f059-4520-8554-74eeb63e5797"
    ]
  }
}

Unassign Orders from their current routes, clearing their tracking data (asynchronous).

THROTTLING

Rate-limit (1 call every 20 seconds)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v2/territories/:territoryId/simulation/:simulationId/scheduling/unassign[?orderIds=<comma_separated_list>]

REQUEST BODY
Property Type Description
orderIds list of String Mandatory. List of one or more Orders to unassign.
QUERYSTRING PARAMETERS [DEPRECATED]
Property Type Description
orderIds comma-separated list of String Mandatory. List of one or more Orders to unassign.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body.
RETURN VALUES (synchronous)
Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification)
RETURN VALUES (asynchronous notification)
Property Type Description
requestId String Request ID associated to the asynchronous request
simulationId UUID Simulation ID
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse

Customer Notifications API

List OrderStep Notifications

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "notifications": [
    {
      "orderStepId": {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      },
      "kind": "SMS",
      "sentTs": 1610115318405,
      "status": "SENT",
      "subject": null,
      "recipient": "+11111111111"
      "bodyPlainText": "Your order #123456 from Company XYZ will be delivered today",
      "bodyHtml": null,
      "errorCode": null,
      "errorName": null
    }
  ]
}

List the notifications that have been generated for an OrderStep. To fetch notifications in bulk for more that a few orders please use the List Orders Notifications API.

THROTTLING

Rate-limit (2 calls every second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/notifications/orders/:orderId/:orderStepType

RETURN VALUES

Property Type Description
notifications list of OrderStepNotification Notifications sent for the specified order step

List Orders Notifications

curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders?key=AUTH_KEY&from=2021-01-07T00%3A00%3A00Z&to=2021-01-10T00%3A00%3A00Z

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders?from=2021-01-07T00%3A00%3A00Z&to=2021-01-10T00%3A00%3A00Z HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "notifications": [
    {
      "orderStepId": {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      },
      "kind": "SMS",
      "sentTs": 1610115318405,
      "status": "SENT",
      "subject": null,
      "recipient": "+11111111111",
      "bodyPlainText": "Your order #123456 from Company XYZ will be delivered today",
      "bodyHtml": null,
      "errorCode": null,
      "errorName": null
    }
  ]
}

List the notifications for all the orders in a territory. The list is restricted to the period of time specified via the from and to query-string parameters, and can span a maximum of 7 days.

THROTTLING

Rate-limit (1 call every 10 minutes)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/notifications/orders?from=YYYY-MM-DDThh:mm:ssZ&to=YYYY-MM-DDThh:mm:ssZ

QUERYSTRING PARAMETERS

Property Type Description
from String ISO 8601 timestamp
to String ISO 8601 timestamp

RETURN VALUES

Property Type Description
notifications list of OrderStepNotification Notifications sent for the specified order step

Proposals API

Compute ProposalsSet

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
  "order":
  {
    "name": "Order coming from Proposals API",
    "loads": {
      "pounds": 400
    },
    "pickup": {
      "location": {
        "address": "100 20th Street West, Jasper, AL 35501, USA"
      },
      "notes": "Order (pickup) for which we want to compute a set of proposals",
      "serviceTimeSec": 1800,
      "customFields": {
        "my custom field": "custom field content",
        "orderId": "abcd1234"
      }
    },
    "delivery": {
      "location": {
        "address": "2001 2nd Ave, Jasper, AL 35501, USA"
      },
      "notes": "Order (delivery) for which we want to compute a set of proposals",
      "serviceTimeSec": 1800,
      "customFields": {
        "my custom field": "custom field content",
        "orderId": "abcd1234"
      }
    },
    "isService": false
  },
  "timeSlots": [
    {
      "pickupTimeWindows": [
        {
          "startSec": 18000,
          "endSec": 19800
        }
      ],
      "deliveryTimeWindows": [
        {
          "startSec": 19800,
          "endSec": 21600
        }
      ],
      "date": "20151204"
    },
    {
      "pickupTimeWindows": [
        {
          "startSec": 45000,
          "endSec": 46800
        }
      ],
      "deliveryTimeWindows": [
        {
          "startSec": 46800,
          "endSec": 50400
        }
      ],
      "date": "20151204"
    },
    {
      "pickupTimeWindows": [
        {
          "startSec": 18000,
          "endSec": 19800
        }
      ],
      "deliveryTimeWindows": [
        {
          "startSec": 19800,
          "endSec": 21600
        }
      ],
      "date": "20151205"
    }
  ],
  "overrideLockedRoutes": true
}

The above command returns JSON structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0"
}

And triggers a ProposalsSetProcessed Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "proposalsSetProcessed",
  "data": {
    "order": {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "geocodeStatus": {
        "delivery": "OK"
      }
    },
    "proposals": [
      {
        "status": "NOT_FOUND"
      },
      {
        "status": "FOUND",
        "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
        "pickupStartSec": 38265,
        "deliveryStartSec": 43549,
        "routeCost": 201675,
        "deltaCost": 10498
      },
      {
        "status": "NOT_FOUND"
      }
    ]
  }
}

Given an Order and a set of desired time slots, computes, for each slot, a “proposal” identifying the best Route that the Order can be assigned to in that slot (asynchronous).

Because of resource saturation or other constraints it may happen that, for some slots, the Order cannot be assigned to any Route. In that case the computed set of proposals will include “empty” proposals.

Once computed, the “set of proposals” is temporarily stored allowing for proposals in the set to be reviewed and, possibly, for one of them to be selected and applied.

THROTTLING

Concurrency-limit (max 3 concurrent computations)
Quantity-limit (max 10 stored results)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals

REQUEST BODY

Property Type Description
order OrderInput Order for which we want to compute a set of proposals. The system will assign a UUID to the Order and return it in the proposalsSetProcessed notification message, in the order.id field.
Note: the Order is only added to the plan when one of the computed proposals is applied.
Note: timeWindows, timeWindowsExceptions and eligibility fields are ignored (see timeSlots below).
timeSlots list of TimeSlot Alternative time-slots applied to the Order’s TimeWindow and Eligibility properties to compute possible assignments
LIMITS: cannot contain more than 7 TimeSlots.
LIMITS: timeSlot’s date cannot be today’s working date (unless today’s working date has zero Approved Routes).
overrideLockedRoutes boolean Optional. Defaults to false.
If set to false UI-defined locks are honored.
If set to true UI-defined locks are ignored (i.e.: all Routes and Vehicles are valid candidates)

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification).
Also used to identify the ProposalsSet object generated as a result of the computation.

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to proposalsSetProcessed
data ProposalsSetProcessed OR ErrorResponse

Get ProposalsSet

curl -X GET https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "requestStatus": "COMPLETED",
  "expiryTs": 1423047900,
  "order": {
    "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "name": "Order 6 - Proposal",
    "eligibility": {
      "type": "any"
    },
    "forceVehicleId": null,
    "priority": 0,
    "loads": {
      "people": 2
    },
    "delivery": {
      "location": {
        "address": "2001 2nd Ave, Jasper, AL 35501, USA"
      },
      "timeWindows": [],
      "notes": "Proposal order to be added via API",
      "serviceTimeSec": 1800,
      "tagsIn": [],
      "tagsOut": [],
      "customFields": {
        "my custom field": "custom field content",
        "orderId": "abcd1234"
      }
    },
    "isService": false
  },
  "proposals": [
    {
      "status": "NOT_FOUND"
    },
    {
      "status": "FOUND",
      "data": {
        "routes": {
          "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
            "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
            "revision": -1,
            "date": "20151204",
            "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "driverId": null,
            "steps": [
              {
                "type": "departure",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 0,
                "startSec": 0,
                "endSec": 28800,
                "driveToNextSec": 2918,
                "distanceToNextMt": 73402,
                "stopIdx": 0,
                "displayLabel": ""
              },
              {
                "type": "pickup",
                "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 31718,
                "startSec": 31718,
                "endSec": 32318,
                "driveToNextSec": 2917,
                "distanceToNextMt": 73549,
                "stopIdx": 1,
                "displayLabel": ""
              },
              {
                "type": "delivery",
                "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 35235,
                "startSec": 35235,
                "endSec": 36135,
                "driveToNextSec": 48,
                "distanceToNextMt": 334,
                "stopIdx": 2,
                "displayLabel": ""
              },
              {
                "type": "delivery",
                "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 38265,
                "startSec": 38265,
                "endSec": 40065,
                "driveToNextSec": 123,
                "distanceToNextMt": 846,
                "stopIdx": 3,
                "displayLabel": ""
              },
              {
                "type": "arrival",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 40188,
                "startSec": 40188,
                "endSec": 40188,
                "driveToNextSec": 0,
                "distanceToNextMt": 0,
                "stopIdx": 4,
                "displayLabel": ""
              }
            ],
            "trackingData": null
          }
        },
        "orders": {
          "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
            "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
            "name": "Order 6 - Proposal",
            "eligibility": {
              "on": "20151204"
            },
            "forceVehicleId": null,
            "priority": 0,
            "loads": {
              "people": 2
            },
            "delivery": {
              "location": {
                "address": "2001 2nd Ave, Jasper, AL 35501, USA"
              },
              "timeWindows": [
                {
                  "startSec": 46800,
                  "endSec": 50400
                }
              ],
              "notes": "Proposal order to be added via API",
              "serviceTimeSec": 1800,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {
                "my custom field": "custom field content",
                "orderId": "abcd1234"
              }
            },
            "isService": false
          },
          "e2524914-3611-433b-9209-3ee59ee3996e": {
            "id": "e2524914-3611-433b-9209-3ee59ee3996e",
            "name": "Order 6",
            "eligibility": {
              "type": "any",
              "onDates": [
                "20151203"
              ]
            },
            "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "priority": 0,
            "loads": {
              "people": 400
            },
            "pickup": {
              "depotId": null,
              "location": {
                "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
                "latLng": [
                  33480873,
                  -86788220
                ],
                "status": "OK"
              },
              "timeWindows": [],
              "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
              "serviceTimeSec": 600,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {}
            },
            "delivery": null,
            "isService": false
          },
          "deb5a845-40f8-42e0-963e-9646531894a4": {
            "id": "deb5a845-40f8-42e0-963e-9646531894a4",
            "name": "order2",
            "eligibility": {
              "type": "on",
              "onDates": [
                "20151205"
              ]
            },
            "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "priority": 0,
            "loads": {},
            "pickup": null,
            "delivery": {
              "depotId": null,
              "location": {
                "address": "33.833605,-87.277556",
                "latLng": [
                  33833604,
                  -87277556
                ],
                "status": "OK"
              },
              "timeWindows": [],
              "notes": "",
              "serviceTimeSec": 900,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {}
            },
            "isService": false
          }
        },
        "vehicles": {
          "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
            "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "idx": 2,
            "externalId": "Vehicle 2",
            "tracked": true,
            "sameSideOfStreet": true,
            "color": "5500FF",
            "settings": {
              "20151203": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {}
              },
              "20151204": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {}
              },
              "20151205": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {}
              }
            }
          }
        },
        "depots": {
          "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
            "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "name": "TEST",
            "setupCost": -1,
            "setupTimeSec": -1,
            "location": {
              "address": "320 20th St W, Jasper, AL 35501, USA",
              "latLng": [
                33831316,
                -87278355
              ],
              "status": "OK"
            },
            "color": "998800"
          }
        },
        "drivers": {
          "a3935987-4944-462f-b602-4a3a12beeeff": {
            "id": "a3935987-4944-462f-b602-4a3a12beeeff",
            "name": "Driver 1",
            "summarizeFutureMobileRoute": false,
            "mobileFutureDaysVisibility": 2,
            "email": "driver1@example.com"
          }
        }
      },
      "routeCost": 201675,
      "deltaCost": 10498
    },
    {
      "status": "NOT_FOUND"
    }
  ]
}

Retrieve the set of proposals identified by proposalsSetId (synchronous).

THROTTLING

Leaky bucket (size:20, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId

RETURN VALUES (synchronous)

ProposalsSet

List ProposalsSets

curl -X GET https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals?key=AUTH_KEY

GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

[
    {
      "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
      "requestStatus": "COMPLETED",
      "expiryTs": 1423047900,
      "order": {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "name": "Order 6 - Proposal",
        "eligibility": {
          "type": "any"
        },
        "forceVehicleId": null,
        "priority": 0,
        "loads": {
          "people": 2
        },
        "delivery": {
          "location": {
            "address": "2001 2nd Ave, Jasper, AL 35501, USA"
          },
          "timeWindows": [],
          "notes": "Proposal order to be added via API",
          "serviceTimeSec": 1800,
          "tagsIn": [],
          "tagsOut": [],
          "customFields": {
            "my custom field": "custom field content",
            "orderId": "abcd1234"
          }
        },
        "isService": false
      },
      "proposals": [
        {
          "status": "NOT_FOUND"
        },
        {
          "status": "FOUND",
          "data": {
            "routes": {
              "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
                "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
                "revision": -1,
                "date": "20151204",
                "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
                "driverId": null,
                "steps": [
                  {
                    "type": "departure",
                    "idleTimeSec": 0,
                    "perStopTimeSec": 0,
                    "arrivalSec": 0,
                    "startSec": 0,
                    "endSec": 28800,
                    "driveToNextSec": 2918,
                    "distanceToNextMt": 73402,
                    "stopIdx": 0,
                    "displayLabel": ""
                  },
                  {
                    "type": "pickup",
                    "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
                    "idleTimeSec": 0,
                    "perStopTimeSec": 0,
                    "arrivalSec": 31718,
                    "startSec": 31718,
                    "endSec": 32318,
                    "driveToNextSec": 2917,
                    "distanceToNextMt": 73549,
                    "stopIdx": 1,
                    "displayLabel": ""
                  },
                  {
                    "type": "delivery",
                    "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
                    "idleTimeSec": 0,
                    "perStopTimeSec": 0,
                    "arrivalSec": 35235,
                    "startSec": 35235,
                    "endSec": 36135,
                    "driveToNextSec": 48,
                    "distanceToNextMt": 334,
                    "stopIdx": 2,
                    "displayLabel": ""
                  },
                  {
                    "type": "delivery",
                    "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
                    "idleTimeSec": 0,
                    "perStopTimeSec": 0,
                    "arrivalSec": 38265,
                    "startSec": 38265,
                    "endSec": 40065,
                    "driveToNextSec": 123,
                    "distanceToNextMt": 846,
                    "stopIdx": 3,
                    "displayLabel": ""
                  },
                  {
                    "type": "arrival",
                    "idleTimeSec": 0,
                    "perStopTimeSec": 0,
                    "arrivalSec": 40188,
                    "startSec": 40188,
                    "endSec": 40188,
                    "driveToNextSec": 0,
                    "distanceToNextMt": 0,
                    "stopIdx": 4,
                    "displayLabel": ""
                  }
                ],
                "trackingData": null
              }
            },
            "orders": {
              "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
                "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
                "name": "Order 6 - Proposal",
                "eligibility": {
                  "on": "20151204"
               },
                "forceVehicleId": null,
                "priority": 0,
                "loads": {
                  "people": 2
                },
                "delivery": {
                  "location": {
                    "address": "2001 2nd Ave, Jasper, AL 35501, USA"
                  },
                  "timeWindows": [
                    {
                      "startSec": 46800,
                      "endSec": 50400
                    }
                  ],
                  "notes": "Proposal order to be added via API",
                  "serviceTimeSec": 1800,
                  "tagsIn": [],
                  "tagsOut": [],
                  "customFields": {
                    "my custom field": "custom field content",
                    "orderId": "abcd1234"
                  }
                },
                "isService": false
              },
              "e2524914-3611-433b-9209-3ee59ee3996e": {
                "id": "e2524914-3611-433b-9209-3ee59ee3996e",
                "name": "Order 6",
                "eligibility": {
                  "type": "any",
                  "onDates": [
                    "20151203"
                  ]
                },
                "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
                "priority": 0,
                "loads": {
                  "people": 400
                },
                "pickup": {
                  "depotId": null,
                  "location": {
                    "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
                    "latLng": [
                      33480873,
                      -86788220
                    ],
                    "status": "OK"
                  },
                  "timeWindows": [],
                  "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
                  "serviceTimeSec": 600,
                  "tagsIn": [],
                  "tagsOut": [],
                  "customFields": {}
                },
                "delivery": null,
                "isService": false
              },
              "deb5a845-40f8-42e0-963e-9646531894a4": {
                "id": "deb5a845-40f8-42e0-963e-9646531894a4",
                "name": "order2",
                "eligibility": {
                  "type": "on",
                  "onDates": [
                    "20151205"
                  ]
                },
                "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
                "priority": 0,
                "loads": {},
                "pickup": null,
                "delivery": {
                  "depotId": null,
                  "location": {
                    "address": "33.833605,-87.277556",
                    "latLng": [
                      33833604,
                      -87277556
                    ],
                    "status": "OK"
                  },
                  "timeWindows": [],
                  "notes": "",
                  "serviceTimeSec": 900,
                  "tagsIn": [],
                  "tagsOut": [],
                  "customFields": {}
                },
                "isService": false
              }
            },
            "vehicles": {
              "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
                "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
                "idx": 2,
                "externalId": "Vehicle 2",
                "tracked": true,
                "sameSideOfStreet": false,
                "color": "5500FF",
                "settings": {
                  "20151203": {
                    "available": true,
                    "notes": "",
                    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "timeWindow": {
                      "startSec": 28800,
                      "endSec": 61200
                    },
                    "flexStartTime": true,
                    "perStopCost": 0,
                    "perStopTimeSec": 0,
                    "maxWorkingTimeSec": 0,
                    "maxDrivingTimeSec": 0,
                    "maxDistanceMt": 0,
                    "maxOrders": 0,
                    "breaks": [],
                    "loadCapacities": {
                      "people": 600
                    },
                    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                    "activationCost": 0,
                    "drivingTimeCost": 2000,
                    "idleTimeCost": 2000,
                    "serviceTimeCost": 2000,
                    "breakTimeCost": 2000,
                    "kmCost": 100,
                    "tags": [
                      "heavy"
                    ],
                    "speedFactor": 100,
                    "minWorkingTimeSec": 0,
                    "minLoadCapacities": {}
                  },
                  "20151204": {
                    "available": true,
                    "notes": "",
                    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "timeWindow": {
                      "startSec": 28800,
                      "endSec": 61200
                    },
                    "flexStartTime": true,
                    "perStopCost": 0,
                    "perStopTimeSec": 0,
                    "maxWorkingTimeSec": 0,
                    "maxDrivingTimeSec": 0,
                    "maxDistanceMt": 0,
                    "maxOrders": 0,
                    "breaks": [],
                    "loadCapacities": {
                      "people": 600
                    },
                    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                    "activationCost": 0,
                    "drivingTimeCost": 2000,
                    "idleTimeCost": 2000,
                    "serviceTimeCost": 2000,
                    "breakTimeCost": 2000,
                    "kmCost": 100,
                    "tags": [
                      "heavy"
                    ],
                    "speedFactor": 100,
                    "minWorkingTimeSec": 0,
                    "minLoadCapacities": {}
                  },
                  "20151205": {
                    "available": true,
                    "notes": "",
                    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                    "timeWindow": {
                      "startSec": 28800,
                      "endSec": 61200
                    },
                    "flexStartTime": true,
                    "perStopCost": 0,
                    "perStopTimeSec": 0,
                    "maxWorkingTimeSec": 0,
                    "maxDrivingTimeSec": 0,
                    "maxDistanceMt": 0,
                    "maxOrders": 0,
                    "breaks": [],
                    "loadCapacities": {
                      "people": 600
                    },
                    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                    "activationCost": 0,
                    "drivingTimeCost": 2000,
                    "idleTimeCost": 2000,
                    "serviceTimeCost": 2000,
                    "breakTimeCost": 2000,
                    "kmCost": 100,
                    "tags": [
                      "heavy"
                    ],
                    "speedFactor": 100,
                    "minWorkingTimeSec": 0,
                    "minLoadCapacities": {}
                  }
                }
              }
            },
            "depots": {
              "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
                "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "name": "TEST",
                "setupCost": -1,
                "setupTimeSec": -1,
                "location": {
                  "address": "320 20th St W, Jasper, AL 35501, USA",
                  "latLng": [
                    33831316,
                    -87278355
                  ],
                  "status": "OK"
                },
                "color": "998800"
              }
            },
            "drivers": {
              "a3935987-4944-462f-b602-4a3a12beeeff": {
                "id": "a3935987-4944-462f-b602-4a3a12beeeff",
                "name": "Driver 1",
                "summarizeFutureMobileRoute": false,
                "mobileFutureDaysVisibility": 2,
                "email": "driver1@example.com"
              }
            }
          },
          "routeCost": 201675,
          "deltaCost": 10498
        },
        {
          "status": "NOT_FOUND"
        }
      ]
    }
]

Retrieve all sets of proposals for the specified territory (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals

RETURN VALUES (synchronous)

List of ProposalsSet

Delete ProposalsSet

curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY

DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

The above command returns JSON structured like this:

{}

Deletes the set of proposals identified by proposalsSetId.
Note: If the computation of the specified set is still in progress it is cancelled.

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId

RETURN VALUES (synchronous)

Empty object

Apply Proposal

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY

POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
    "proposalsIndexes": [
      0,1
    ],
    "ignoreRevision": true,
    "costPercentThreshold": 10
}

The above command returns JSON structured like this:

{
  "requestId": "16e00aeb-7c2b-46d2-b0c8-8b7ccc9c7060"
}

And triggers an ProposalApplied Notification (POSTed to the callback URL) structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "proposalApplied",
  "data": {
    "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
    "proposalIndexApplied": 1
  }
}

Accept the requested proposal from the given set of proposals, adding the Order to the plan and assigning it to the Route identified by the selected proposal (asynchronous).

The default behavior appies the proposal only if the revision number of the Route identified by the proposal has not changed since the proposals computation. It’s possible to enable a more “smart” behavior that will try to insert anyway the proposal within the current route (i.e. the one with the revision number changed) in the same time-slot chosen for the original route, and performs some validation to see if it still fit.

If the selected proposal is not applicable the message within the response will contain a list of the proposals that were computed but not chosen by the user and that are still applicable to the updated Route, if any.

Note: If two or more proposals are passed in input, the first one that is acceptable will be applied.

Note: Successfully applying a proposal automatically removes its owning ProposalsSet, freeing up room for computing a new set of proposals

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId

REQUEST BODY

Property Type Description
proposalsIndexes list of int List of zero-based indexes: each index i corresponds to i-th proposal to be applied within the set of proposals.
If multiple indexes are passed, the first compatible result in the list is applied.
ignoreRevision boolean Optional. Default to false.
If set to false the proposal will be applied only if the revision of the Route identified by the proposal has not changed since the proposals computation.
If set to true and the revision of the Route in the proposal changed, the proposal will be applied anyway within the identified time-slot. Then some validation will be performed to check if the route obtained is valid (no violations added and total cost under the given threshold). If the route is valid, the new route (including the proposal order) overwrites the old one, otherwise the request will fail.
costPercentThreshold int Optional. The scheduling of the proposal order within the route in case of changed revision can increase the route cost from the initial proposal. This value sets a maximum allowed amount of cost increase, in percentage. E.g. if costPercentThreshold is set to 10, the new route containing the proposal order will not be accepted in case its cost is more than 10% higher respect to the cost of the original proposal route computed.
Note: Used only if ignoreRevision is set to true.

RETURN VALUES (synchronous)

Property Type Description
requestId String Request ID assigned to the asynchronous request (reported in the asynchronous notification).

RETURN VALUES (asynchronous notification)

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to proposalApplied
data ProposalApplied OR ErrorResponse

GPS Tracking API

List GPS Devices

curl https://wwrm.workwave.com/api/v1/gps/devices?key=AUTH_KEY

GET /api/v1/gps/devices HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "devices": {
    "40519": {
      "id": "40519",
      "label": "Green Van - SBA 1234A" ,
      "category": "PHYSICAL",
      "providerName": "WWGPS",
      "active": true
    },
    "41267": {
      "id": "41267",
      "label": "Red Van - SBA 7231B" ,
      "category": "PHYSICAL",
      "providerName": "WWGPS",
      "active": true
    },
    "42676": {
      "id": "42676",
      "label": "Yellow Van - SBA 6183A" ,
      "category": "PHYSICAL",
      "providerName": "WWGPS",
      "active": true
    },
    "57290": {
      "id": "57290",
      "label": "Alice's Phone",
      "category": "MOBILE",
      "providerName": "WWGPS",
      "active": true
    },
    "57291": {
      "id": "57291",
      "label": "Bob's Phone",
      "category": "MOBILE",
      "providerName": "WWGPS",
      "active": true
    }
  }
}

If using the WWGPS tracking Provider, list all GPS devices as provisioned on the connected WorkWave GPS service (synchronous).
If using one of the 3rd party integrated tracking Provider, list all GPS devices provisioned on all the integrations configured on the account (synchronous).
A GPS device can be either PHYSICAL (e.g.: a GPS unit installed in a vehicle) or MOBILE (e.g.: a smartphone where the WorkWave Route Manger App is installed).

THROTTLING

Rate-limit (1 call every 10 secs)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/gps/devices

RETURN VALUES

Property Type Description
devices map[String]GpsDevice A map where the key is the GPS deviceId and the value is the associated GpsDevice object

List Current GPS Info

curl https://wwrm.workwave.com/api/v1/gps/devices/current?key=AUTH_KEY

GET /api/v1/gps/devices/current HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
  "currentInfos": {
    "40519": {
      "id": "40519",
      "latLng": [
        33817872,
        -87266893
      ],
      "ts": 1449150077,
      "heading": 60,
      "speedMs": 7,
      "providerName": "WWGPS",
      "active": true
    },
    "41267": {
      "id": "41267",
      "latLng": [
        33480873,
        -86788220
      ],
      "ts": 1449142877,
      "heading": 101,
      "speedMs": 9,
      "providerName": "WWGPS",
      "active": true
    },
    "42676": {
      "id": "42676",
      "latLng": [
        33480873,
        -86788220
      ],
      "ts": 1449154517,
      "heading": 242,
      "speedMs": 0,
      "providerName": "WWGPS",
      "active": true
    },
    "57290": {
      "id": "57290",
      "latLng": [
        33833604,
        -87277556
      ],
      "ts": 1449156217,
      "heading": 342,
      "speedMs": 20,
      "providerName": "WWGPS",
      "active": true
    },
    "57291": {
      "id": "57291",
      "latLng": [
        33836824,
        -87266029
      ],
      "ts": 1449155557,
      "heading": 164,
      "speedMs": 0,
      "providerName": "WWGPS",
      "active": true
    }
  }
}

Return last-known/most-recent information about all provisioned GPS devices. This includes timestamp, position, heading and speed (synchronous).

THROTTLING

Rate-limit (1 call every 10 secs)

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/gps/devices/current

RETURN VALUES

Property Type Description
currentInfos map[String]GpsSample A map where the key is the GPS deviceId and the value is the associated GpsSample object

WebHook API

List WebHook Subscription

curl https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY

GET /api/v1/webhooksubscriptions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com

The above command returns JSON structured like this:

{
    "subscriptions": {
        "0ed46547-a79c-48b4-b108-4ccd98d44d8b": {
            "id": "0ed46547-a79c-48b4-b108-4ccd98d44d8b",
            "events": [
                "ORDER_UPDATED"
            ],
            "territoryIds": [
                "0c8bcd10-225a-4acd-a47f-12d1e3077891"
            ],
            "url": "https://my.server.com/webhook-test-1",
            "hmacSecret": "abcd123",
            "enabled": "true",
            "queueBy": "SUBSCRIPTION",
            "headers": {
                "testHeader": "testHeaderBody"
            },
            "createTs": "2022-02-17T09:29:27.6167653Z"
        },
        "2e901af2-8d1f-4bf8-825a-6a57fe0b5372": {
            "id": "2e901af2-8d1f-4bf8-825a-6a57fe0b5372",
            "events": [],
            "territoryIds": [],
            "enabled": false,
            "queueBy": "TERRITORY",
            "url": "https://my.server.com/webhook-test-2",
            "headers": {},
            "createTs": "2022-02-16T13:27:26.0062027Z"
        }
    }
}

Returns all the WebHook Subscriptions active for the invoking account (synchronous).

HTTP REQUEST

GET https://wwrm.workwave.com/api/v1/webhooksubscriptions

THROTTLING

Leaky bucket (size:1, refill: 1 per seconds)

RETURN VALUES

Property Type Description
subscriptions map[UUID]WebHookSubscription A map where the key is the WebHook Subscription ID and the value is the WebHookSubscription correlated. It contains all the WebHook Subscription active for the invoking account.

Add WebHook Subscription

curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY

POST /api/v1/webhooksubscriptions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
    "subscriptions": [
        {
            "events": [
                "ORDER_UPDATED"
            ],
            "territoryIds": [
                "0c8bcd10-225a-4acd-a47f-12d1e3077891"
            ],
            "url": "https://my.server.com/webhook-test-1",
            "hmacSecret": "abcd123",
            "enabled": true,
            "queueBy": "SUBSCRIPTION",
            "headers": {
                "testHeader": "testHeaderBody"
            }
        },
        {
            "events": [],
            "territoryIds": [],
            "url": "https://my.server.com/webhook-test-2",
            "enabled": false,
            "queueBy": "TERRITORY",
            "headers": {}
        }
    ]
}

The above command returns JSON structured like this:

{
    "subscriptions": {
        "0ed46547-a79c-48b4-b108-4ccd98d44d8b": {
            "id": "0ed46547-a79c-48b4-b108-4ccd98d44d8b",
            "events": [
                "ORDER_UPDATED"
            ],
            "territoryIds": [
                "0c8bcd10-225a-4acd-a47f-12d1e3077891"
            ],
            "url": "https://my.server.com/webhook-test-1",
            "enabled": true,
            "queueBy": "SUBSCRIPTION",
            "hmacSecret": "abcd123",
            "headers": {
                "testHeader": "testHeaderBody"
            },
            "createTs": "2022-02-17T09:29:27.6167653Z"
        },
        "2e901af2-8d1f-4bf8-825a-6a57fe0b5372": {
            "id": "2e901af2-8d1f-4bf8-825a-6a57fe0b5372",
            "events": [],
            "territoryIds": [],
            "url": "https://my.server.com/webhook-test-2",
            "enabled": false,
            "queueBy": "TERRITORY",
            "headers": {},
            "createTs": "2022-02-16T13:27:26.0062027Z"
        }
    }
}

Subscribe to a list of TerritoryIds and events with a WebHook URL (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

POST https://wwrm.workwave.com/api/v1/webhooksubscriptions

REQUEST BODY

Property Type Description
subscriptions List of WebHookSubscriptionInput The list of WebHookSubscription requested

RETURN VALUES

Property Type Description
subscriptions Map [UUID]WebHookSubscription A map where the subscription is the WebHook Subscription ID and teh value is the WebHookSubscription created.

Update WebHook Subscription

curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/webhooksubscriptions/2e901af2-8d1f-4bf8-825a-6a57fe0b5372?key=AUTH_KEY

PUT /api/v1/webhooksubscriptions/2e901af2-8d1f-4bf8-825a-6a57fe0b5372 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json

{
    "enabled": true
}

The above command returns JSON structured like this:

{
    "enabled": true
}

Enable or disable an existing WebHook Subscription.

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

PUT https://wwrm.workwave.com/api/v1/webhooksubscriptions/:subscriptionId

REQUEST BODY

Property Type Description
enabled boolean The desired state for the Subscription.

RETURN VALUES

Property Type Description
enabled boolean The set state for the Subscription.

Delete WebHook Subscription

curl https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY&ids='comma separated ids'

DELETE /api/v1/webhooksubscriptions[?ids=<comma_separated_list>] HTTP/1.0

The above command returns a response like this:

true

And in case the test fails:

{
    "errorCode": 100,
    "errorMessage": "ids list cannot be empty"
}

Delete the WebHook Subscriptions (synchronous).

THROTTLING

Leaky bucket (size:10, refill: 1 per second)

HTTP REQUEST

DELETE https://wwrm.workwave.com/api/v1/webhooksubscriptions[?ids=<comma_separated_list>]

QUERYSTRING PARAMETERS

Property Type Description
ids comma-separated list of String Ids of Subscriptions to be deleted.

Note: if only the * character is sent as ids, all the subscription for the account will be deleted.

LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200.

If the request is successfully completed, the value response will contains the true value in the body as plain text.

Asynchronous Notifications

Mechanics

Async notifications are POSTed to the configured Callback URL under the following circumstances:

  1. to notify the completion of an asynchronous API request
  2. to notify that some Orders changed as the result of either an API request or a manual request performed via the Web Application
  3. to notify that Routes for a given date have been marked as “Approved”

When one of the above events happens, an HTTP(S) POST request is sent from one the WorkWave Route Manager servers to the Callback URL.

Different notifications carry different information encoded in JSON format in the request body. The format of each body type is outlined in the following Chapters.

The remote server is expected to accept the TCP connection within 5 seconds and return an HTTP 200 OK code within 15 seconds.
Failing that, the Callback URL is invoked again up to 5 times according to the following retry strategy:

It is therefore strongly advised not to perform any time-consuming processing logic as part of the thread that receives the notification request, but to delegate such actions to other threads so that the receiving thread can immediately reply with a 200 OK response.

OrdersChanged Notification

Adding new Orders triggers a notification structured like this:

{
  "requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      },
      {
        "id": "89009ba2-285f-47a1-8b91-5524d8f31b16",
        "geocodeStatus": {
          "delivery": "LOW_ACCURACY"
        }
      },
      {
        "id": "6a0c1374-e07c-410d-98d2-dd7be1f02ffa",
        "geocodeStatus": {
          "delivery": "NOT_FOUND"
        }
      },
      {
        "id": "3d499ad0-14f6-4a38-acd8-05b8269dec78",
        "geocodeStatus": {
          "delivery": "POSTCODE_ISSUE"
        }
      },
      {
        "id": "a5682ad9-97e8-4719-9bb6-eecfcfb8606b",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "updated": [],
    "deleted": []
  }
}

Updating or replacing an existing Order triggers a notification structured like this:

{
  "requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [
      {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "geocodeStatus": {
          "delivery": "OK"
        }
      }
    ],
    "deleted": []
  }
}

Deleting Orders triggers a notification structured like this:

{
  "requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "ordersChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
    ]
  }
}

Notifies that some Orders’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Orders API or of a manual operation performed via the Web Application.

In general, any operation that changes Orders’ data (create/update/delete) triggers an ordersChanged notification.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and if not, issue a Get Orders request to fetch the details of the updated Order(s).

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to ordersChanged
data OrdersChanged OR ErrorResponse Details about the outcome of the change event

VehiclesChanged Notification

Adding a new Vehicle (from the UI) triggers a notification structured like this:

{
  "requestId": null,
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [
        "875cceab-0952-4101-9db3-e524dbec9a75"
    ],
    "updated": [],
    "deleted": []
  }
}

Updating an existing Vehicle triggers a notification structured like this:

{
  "requestId": "302f2060-c132-4079-8565-9f543ea581ea",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [
        "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
    ],
    "deleted": []
  }
}

Deleting a Vehicle (from the UI) triggers a notification structured like this:

{
  "requestId": null,
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehiclesChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
        "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
    ]
  }
}

Notifies that some Vehicles’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Vehicles API or of a manual operation performed via the Web Application.

In general, any operation that changes Vehicles’ data (create/update/delete) triggers a vehiclesChanged notification.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and if not, issue a List Vehicles or a Get Vehicle Settings request to fetch the details of the updated Vehicle(s).

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehiclesChanged
data VehiclesChanged OR ErrorResponse Details about the outcome of the change event

DriversChanged Notification

Adding a new Driver triggers a notification structured like this:

{
  "requestId": "88b79f3b-28bf-4bd6-82ae-9c523f3cc20b",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [
        "0129724f-b80d-4011-ab91-3e4ae2f62896"
    ],
    "updated": [],
    "deleted": []
  }
}

Updating an existing Driver triggers a notification structured like this:

{
  "requestId": "9ca2501f-19f1-42b0-b17c-3ebe585776c6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [],
    "updated": [
        "a3935987-4944-462f-b602-4a3a12beeeff"
    ],
    "deleted": []
  }
}

Deleting a Driver triggers a notification structured like this:

{
  "requestId": "aac2fe79-5cc9-485a-9a24-b48d3d03db49",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "driversChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
        "a08213e6-673f-4efc-955e-2bf587813162"
    ]
  }
}

Notifies that some Drivers’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Drivers API or of a manual operation performed via the Web Application.

In general, any operation that changes Drivers’ data (create/update/delete) triggers a driversChanged notification.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and if not, issue a List Drivers request to fetch the details of the updated Drivers.

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to driversChanged
data DriversChanged OR ErrorResponse Details about the outcome of the change event

VehicleDriverAssignmentsChanged Notification

Replacing Vehicle-Drivers Assignments triggers a notification structured like this:

{
  "requestId": "c3f7257a-3c5d-4870-bddc-e8845da1a227",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehicleDriverAssignmentsChanged",
  "data": {}
}

Notifies that some Vehicle-Driver assignments have changed.

This can be the result of an asynchronous API request such as the ones described at Vehicle-Driver Assignments API or of a manual operation performed via the Web Application.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and if not, issue a Get Driver Assignments request to fetch the details of the updated assignments.

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to vehicleDriverAssignmentsChanged
data empty object OR ErrorResponse

ExecutionEventsProcessed Notification

Sending Execution Events triggers a notification structured like this:

{
  "requestId": "a6f01d6b-a085-4812-8784-48d26d888809",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "executionEventsProcessed",
  "data": {
    "processed": [
      "OK",
      "OK",
      "ERROR_VEHICLE_NOT_TRACKED",
      "OK_WARN_LATLNG_OUT_OF_BOUNDS",
      "OK"
    ]
  }
}

Sending Execution Events while a WebApp-initiated Editing Transaction is in progress triggers a notification structured like this:

{
  "requestId": "303dd2b5-22c4-4fe9-9586-a6b168d96658",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "executionEventsProcessed",
  "data": {
    "processed": [
      "POSTPONED",
      "POSTPONED",
      "POSTPONED"
    ]
  }
}

Notifies that an API-initiated Send Execution Events request completed.

REQUEST BODY

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to executionEventsProcessed
data ExecutionEventsProcessed OR ErrorResponse Details about the outcome of the update event

ApprovedRoutesChanged Notification

Approving Routes and/or revoking Routes approval triggers a notification structured like this:

{
  "requestId": "94accf16-dab4-4a6d-85b1-eda4bff10842",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "approvedRoutesChanged",
  "data": {
    "approved": ["20151204", "20151205"],
    "revoked": ["20151206"]
  }
}

Notifies changes to dates where Routes have been either marked as approved (i.e.: ready to be dispatched and visible to mobile apps) or have been revoked approval (i.e.: not ready to be dispatched, no more visible to mobile apps).

This is the result of either API-initiated Approve Routes or Revoke Routes requests or a manual operation performed via the Web Application (via the “Approve and Dispatch” button).

An application interested in this type of notification would, upon receiving it, typically issue a List Approved Routes request to retrieve details about the approved Routes.

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to approvedRoutesChanged
data ApprovedRoutesChanged OR ErrorResponse Details about the outcome of the update event

SchedulingCompleted Notification

Building Routes triggers a notification structured like this:

{
  "requestId": "758aa6e2-f450-4f2e-9559-b928e39fb5f9",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {}
}

Fitting-In Unassigned Orders triggers a notification structured like this:

{
  "requestId": "13d8ddf5-7fbc-49e5-a2b3-cb4d10b80827",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
      "603a348f-7fcc-4bdc-8f4a-ec10a68547e0"
    ]
  }
}

Unassigning Orders triggers a notification structured like this:

{
  "requestId": "1bf2f905-522f-42ab-bc06-d2bfb5dd4f06",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderIds": [
      "603a348f-7fcc-4bdc-8f4a-ec10a68547e0"
    ]
  }
}

Assigning OrderSteps triggers a notification structured like this:

{
  "requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderSteps": [
      {
        "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "type": "delivery"
      }
    ]
  }
}

Notifies that an API-initiated scheduling request completed.

This is the result of the asynchronous API requests described at Scheduling API.

REQUEST BODY

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to schedulingCompleted
data SchedulingCompleted OR ErrorResponse Details about the outcome of the update event

ProposalsSetProcessed Notification

Compute ProposalsSet triggers a notification structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "proposalsSetProcessed",
  "data": {
    "order": {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "geocodeStatus": {
        "delivery": "OK"
      }
    },
    "proposals": [
      {
        "status": "NOT_FOUND"
      },
      {
        "status": "FOUND",
        "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
        "pickupStartSec": 38265,
        "deliveryStartSec": 43549,
        "routeCost": 201675,
        "deltaCost": 10498
      },
      {
        "status": "NOT_FOUND"
      }
    ]
  }
}

Notifies that of a set of proposals has been computed and stored for review and proposal application

REQUEST BODY

Property Type Description
requestId String Request ID associated to the asynchronous request, also doubles as the ID of the stored ProposalsSet
territoryId UUID Territory ID
event String Set to proposalsSetProcessed
data ProposalsSetProcessed OR ErrorResponse Details about the outcome of the processed event

ProposalApplied Notification

Apply Proposal triggers a notification structured like this:

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "schedulingCompleted",
  "data": {
    "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
    "proposalIndexApplied": 1
  }
}

Notifies the application of a proposal, resulting in the addition of the Order to the plan and its assignment to the Route identified by the selected proposal.

REQUEST BODY

Property Type Description
requestId String Request ID associated to the asynchronous request
territoryId UUID Territory ID
event String Set to proposalApplied
data ProposalApplied OR ErrorResponse Details about the outcome of the processed event

RegionsChanged Notification

Adding a new Region triggers a notification structured like this:

{
  "requestId": "7d69fd36-3841-4ec6-bdc4-775f5e550918",
  "territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
  "event": "regionsChanged",
  "data": {
    "created": [
        "6543c0c1-d55e-46e1-ae3c-65d26239351c"
    ],
    "updated": [],
    "deleted": []
  }
}

Updating an existing Region triggers a notification structured like this:

{
  "requestId": "f97f7a00-8751-4bd7-920e-c5a7cdca2958",
  "territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
  "event": "regionsChanged",
  "data": {
    "created": [],
    "updated": [
        "584cc8bf-3fee-41a2-81f1-8ab1d6b15269"
    ],
    "deleted": []
  }
}

Deleting a Region triggers a notification structured like this:

{
  "requestId": "72cbfae8-d75e-444a-8b98-6a4da3e91452",
  "territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
  "event": "regionsChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
        "539d3609-58bc-4445-b068-69cb8d977ef9"
    ]
  }
}

Notifies that some Regions’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Regions API or a manual operation performed via the Web Application.

In general, any operation that change Regions’ data (create/update/delete) triggers a regionsChanged notification.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and, if not, issue a List Regions request to fetch the details of the updated Regions.

REQUEST BODY

Property Type Description
requestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to regionsChanged
data RegionsChanged OR ErrorResponse Details about the outcome of the change event

DepotsChanged Notification

Adding a new Depot triggers a notification structured like this:

{
  "requestId": "88b79f3b-28bf-4bd6-82ae-9c523f3cc20b",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [
        "0129724f-b80d-4011-ab91-3e4ae2f62896"
    ],
    "updated": [],
    "deleted": []
  }
}

Updating an existing Depot triggers a notification structured like this:

{
  "requestId": "9ca2501f-19f1-42b0-b17c-3ebe585776c6",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [],
    "updated": [
        "a3935987-4944-462f-b602-4a3a12beeeff"
    ],
    "deleted": []
  }
}

Deleting a Depot triggers a notification structured like this:

{
  "requestId": "aac2fe79-5cc9-485a-9a24-b48d3d03db49",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "depotsChanged",
  "data": {
    "created": [],
    "updated": [],
    "deleted": [
        "a08213e6-673f-4efc-955e-2bf587813162"
    ]
  }
}

Notifies that some Depots’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Depots API or of a manual operation performed via the Web Application.

In general, any operation that changes Depots’ data (create/update/delete) triggers a depotsChanged notification.

An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId) and if not, issue a List Depots request to fetch the details of the updated Depots.

REQUEST BODY

Property Type Description
requestId String Request ID associated to the asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
event String Set to depotsChanged
data DepotsChanged OR ErrorResponse Details about the outcome of the processed event

WebHook Notifications

Mechanics

WebHook notifications are POSTed to the WebHook URL set in the WebHook Subscription when the event the subscription refers to happens in the Plan, if the subscription is enabled. A single subscription can refer to multiple events.

Different notifications carry different information encoded in JSON format in the request body. The format of each body type is outlined in the following Chapters.

The remote server is expected to accept the TCP connection within 10 seconds and return an HTTP 200 OK code within 10 seconds.
Failing that, the invokation is repeated according to the following retry strategy:

If you need to do any processing that could take more than 10 seconds in response to a webhook, it’s strongly advised to queue such actions for later processing in your system upon receiving the webhook and immediatedly reply with a 200 OK response.

Note: If the remote server replies with an HTTP code of 404 error, the subscription will be disabled immediately.
If the remote server replies with an HTTP code that does not belong to the 2xx success code class and it’s not 404 error for more than a few days, the subscription will be disabled.

When disabled, a subscription is still present, but will not send any notification for the events it refers to. The state can be modified with the Update WebHook Subscription invokation.

Orders Notification

Changes to an order triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_ADDED",
  "orders": {
    "571bcb74-8905-4c77-9ff9-3517958f65b0": {
      "id": "571bcb74-8905-4c77-9ff9-3517958f65b0",
      "name": "New Order 1",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": {
        "depotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
        "location": null,
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "189 Frelinghuysen Ave, Newark, NJ 07114, USA",
          "latLng": [
            40715249,
            -74188244
          ],
          "status": "OK",
          "geoAddress": "189 Frelinghuysen Ave, Newark, NJ 07114, USA"
        },
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "isService": false,
      "integrationData": null
    }
  },
  "depots": {
    "0363f92b-f67a-4f71-8e2a-e6ebd7f54633": {
      "id": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
      "name": "Depot 1",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "27 Scotland Rd, Elizabeth, NJ 07208, USA",
        "latLng": [
          40679643,
          -74217459
        ],
        "status": "OK",
        "geoAddress": "27 Scotland Road, Elizabeth, NJ 07208, USA"
      },
      "color": null
    }
  }
}

Notifies that some Orders’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Orders API or of a manual operation performed via the Web Application.

In general, any operation that changes Orders’ data (create/update/delete) triggers a WebHook notification that contains the new Order information.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the order changed case can be “ORDER_ADDED”, “ORDER_UPDATED” or “ORDER_DELETED”
orders map[UUID]Order A map where the key is the OrderId and the value is the associated Order object
depots map[UUID]Depot Optional, a map where the key is the Depot Id and the value is the associated Depot Object

OrderStep Assignment Notification

Changes to an order triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_STEP_ASSIGNMENT_UPDATED",
  "orders": {
    "0db3c44e-cfa1-4cd5-853d-57749cc3632e": {
      "id": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
      "name": "New Order 1",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": {
        "depotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
        "location": null,
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "592 Hawthorne Ave, Newark, NJ 07112, USA",
          "latLng": [
            40721404,
            -74218523
          ],
          "status": "OK",
          "geoAddress": "592 Hawthorne Ave, Newark, NJ 07112, USA"
        },
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "isService": false,
      "integrationData": null
    }
  },
  "assignments": [
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "pickup"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": false,
      "displayLabel": "1"
    },
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "delivery"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": false,
      "displayLabel": "2"
    }
  ],
  "depots": {
    "0363f92b-f67a-4f71-8e2a-e6ebd7f54633": {
      "id": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
      "name": "Depot 1",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "27 Scotland Rd, Elizabeth, NJ 07208, USA",
        "latLng": [
          40679643,
          -74217459
        ],
        "status": "OK",
        "geoAddress": "27 Scotland Road, Elizabeth, NJ 07208, USA"
      },
      "color": null
    }
  },
  "vehicles": {
    "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0": {
      "id": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "idx": 3,
      "externalId": "Vehicle3",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "5500FF",
      "gpsDeviceId": null,
      "settings": {
        "20220223": {
          "available": true,
          "notes": "",
          "departureDepotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
          "arrivalDepotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
          "timeWindow": {
            "startSec": 19800,
            "endSec": 34200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "breaks": [],
          "loadCapacities": {},
          "regionIds": [],
          "activationCost": 0,
          "drivingTimeCost": 0,
          "idleTimeCost": 5000,
          "serviceTimeCost": 5000,
          "breakTimeCost": 5000,
          "kmCost": 31,
          "tags": [],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "drivers": {
    "e6d9b705-f537-47a8-bfc1-2dd2e9620013": {
      "id": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "name": "Driver 3",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "test@workwave.com",
      "gpsDeviceId": null
    }
  }
}

Notifies that some OrderSteps assignment data has changed.

This can be the result of an asynchronous API request or of a manual operation performed via the Web Application.

In general, any operation that add or update an OrderStep to a route or the approval of the route will trigger this a WebHook notification.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the order changed case can be “ORDER_STEP_ASSIGNMENT_UPDATED” or “ORDER_STEP_DISPATCH_UPDATED”.
orders map[UUID]Order A map where the key is the OrderId and the value is the associated Order object
assignments list of OrderStepAssignment Informations regarding the assignment of the OrderStep(s)
vehicles map[UUID]Vehicle A map where the key is the vehicleId and the value is the associated Vehicle object
drivers map[UUID]Driver A map where the key is the driverId and the value is the associated Driver object
depots map[UUID]Depot Optional, a map where the key is the Depot Id and the value is the associated Depot Object

OrderStep Status Change Notification

Changes to an order triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_STEP_DONE",
  "orders": {
    "0db3c44e-cfa1-4cd5-853d-57749cc3632e": {
      "id": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
      "name": "New Order 1",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": {
        "depotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
        "location": null,
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "delivery": {
        "depotId": null,
        "location": {
          "address": "592 Hawthorne Ave, Newark, NJ 07112, USA",
          "latLng": [
            40721404,
            -74218523
          ],
          "status": "OK",
          "geoAddress": "592 Hawthorne Ave, Newark, NJ 07112, USA"
        },
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "isService": false,
      "integrationData": null
    }
  },
  "assignments": [
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "pickup"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": false,
      "displayLabel": "1"
    },
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "delivery"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": false,
      "displayLabel": "2"
    }
  ],
  "depots": {
    "0363f92b-f67a-4f71-8e2a-e6ebd7f54633": {
      "id": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
      "name": "Depot 1",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "27 Scotland Rd, Elizabeth, NJ 07208, USA",
        "latLng": [
          40679643,
          -74217459
        ],
        "status": "OK",
        "geoAddress": "27 Scotland Road, Elizabeth, NJ 07208, USA"
      },
      "color": null
    }
  },
  "vehicles": {
    "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0": {
      "id": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "idx": 3,
      "externalId": "Vehicle3",
      "tracked": true,
      "sameSideOfStreet": true,
      "color": "5500FF",
      "gpsDeviceId": null,
      "settings": {
        "20220223": {
          "available": true,
          "notes": "",
          "departureDepotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
          "arrivalDepotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
          "timeWindow": {
            "startSec": 19800,
            "endSec": 34200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "breaks": [],
          "loadCapacities": {},
          "regionIds": [],
          "activationCost": 0,
          "drivingTimeCost": 0,
          "idleTimeCost": 5000,
          "serviceTimeCost": 5000,
          "breakTimeCost": 5000,
          "kmCost": 31,
          "tags": [],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {}
        }
      }
    }
  },
  "drivers": {
    "e6d9b705-f537-47a8-bfc1-2dd2e9620013": {
      "id": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "name": "Driver 3",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "test@workwave.com",
      "gpsDeviceId": null
    }
  },
  "trackingData": {
    "delivery-0db3c44e-cfa1-4cd5-853d-57749cc3632e": {
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "timeInSec": -1,
      "timeInLatLng": null,
      "timeOutSec": 7200,
      "timeOutLatLng": [
        45000435,
        8106819
      ],
      "status": "done",
      "statusSec": 7200,
      "statusLatLng": [
        45000435,
        8106819
      ],
      "statusReason": null,
      "timeInDetectedSec": -1,
      "timeInDetectedLatLng": null,
      "timeOutDetectedSec": -1,
      "timeOutDetectedLatLng": null,
      "pods": null
    }
  }
}

Notifies that some OrderSteps assignment data has changed.

This can be the result of an asynchronous API request or of a manual operation performed via the Web Application.

Any operation that update the status of the OrderStep will trigger this WebHook notification.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the order changed case can be “ORDER_STEP_DONE” or “ORDER_STEP_RESCHEDULED”
orders map[UUID]Order A map where the key is the OrderId and the value is the associated Order object
assignments list of OrderStepAssignment Informations regarding the assignment of the OrderStep(s)
vehicles map[UUID]Vehicle A map where the key is the vehicleId and the value is the associated Vehicle object
drivers map[UUID]Driver A map where the key is the driverId and the value is the associated Driver object
trackingData map[String]TrackingData A map where the key is composed by the OrderStepId in the form of type-OrderId, and the value is the associated Tracking Data
depots map[UUID]Depot Optional, a map where the key is the Depot Id and the value is the associated Depot Object

OrderStep Unassign Notification

Changes to an order triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_STEP_REVOKED",
  "orders": {
    "8cc0a827-1fce-4706-8545-5ba2f442ab4d": {
      "id": "8cc0a827-1fce-4706-8545-5ba2f442ab4d",
      "name": "New Order 13",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "280 Eisenhower Pkwy, Livingston, NJ 07039, USA",
          "latLng": [
            40797527,
            -74340623
          ],
          "status": "OK",
          "geoAddress": "280 Eisenhower Pkwy, Livingston, NJ 07039, USA"
        },
        "timeWindows": [],
        "timeWindowExceptions": {},
        "notes": "",
        "phone": null,
        "email": null,
        "serviceTimeSec": 0,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {},
        "barcodes": []
      },
      "isService": false,
      "integrationData": null
    }
  },
  "orderStepIds": [
    {
      "orderId": "8cc0a827-1fce-4706-8545-5ba2f442ab4d",
      "type": "delivery"
    }
  ]
}

Notifies that some OrderSteps assignment data has changed.

This can be the result of an asynchronous API request or of a manual operation performed via the Web Application.

In general, any operation that remove an OrderStep to a route or the revoke of the route will trigger this a WebHook notification.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the order changed case can be “ORDER_STEP_REVOKED” or “ORDER_STEP_UNASSIGNED”
orders map[UUID]Order A map where the key is the OrderId and the value is the associated Order object
orderStepIds list of OrderStepIdentifier The OrderStep Identifiers of all the OrderSteps Removed or Revoked
depots map[UUID]Depot Optional, a map where the key is the Depot Id and the value is the associated Depot Object. Present if one of the step refers to a Depot (e.g. Pickup & Delivery).

OrderStep Tracking Data Update Notification [Deprecated]

Changes to an order step tracking data triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_STEP_TRACKING_DATA_UPDATE",
  "assignments": [
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "pickup"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": true,
      "displayLabel": "1.1"
    },
    {
     "orderStepId": {
        "orderId": "7a433c07-a605-4684-b785-4a7568b6401b",
        "type": "delivery"
      },
      "vehicleId": "492c1f4b-467d-4349-ae0a-0947f0baa4da",
      "driverId": "cb482f01-d52e-4322-bac2-ddb78f0f2bec",
      "date": "20220223",
      "isApproved": true,
      "displayLabel": "1.3"
    },
    {
      "orderStepId": {
        "orderId": "11afce76-27aa-43c8-8b9b-cd0a2b6b937b",
        "type": "delivery"
      },
      "isApproved": false
    }
  ],
  "trackingData": {
    "delivery-0db3c44e-cfa1-4cd5-853d-57749cc3632e": {
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "timeInSec": -1,
      "timeInLatLng": null,
      "timeOutSec": 7200,
      "timeOutLatLng": [
        45000435,
        8106819
      ],
      "status": "done",
      "statusSec": 7200,
      "statusLatLng": [
        45000435,
        8106819
      ],
      "statusReason": null,
      "timeInDetectedSec": -1,
      "timeInDetectedLatLng": null,
      "timeOutDetectedSec": -1,
      "timeOutDetectedLatLng": null,
      "pods": null
    },
    "delivery-7a433c07-a605-4684-b785-4a7568b6401b": null,
    "delivery-11afce76-27aa-43c8-8b9b-cd0a2b6b937b": null
  }
}

Notifies that some OrderSteps TrackingData has changed.

This can be the result of an execution Event sent from mobile or via API request, or a manual operation performed via the Web Application.

In general, any operation that updates the TrackingData of an OrderStep will trigger this WebHook notification.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the OrderStep tracking data changed case must be “ORDER_STEP_TRACKING_DATA_UPDATE”
assignments list of OrderStepAssignment Informations regarding the assignment of the OrderStep(s)
trackingData map[String]TrackingData A map where the key is composed by the OrderStepId in the form of type-OrderId, and the value is the associated Tracking Data

OrderStep Tracking Data Updated Notification

Changes to an order step tracking data triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "ORDER_STEP_TRACKING_DATA_UPDATED",
  "assignments": [
    {
      "orderStepId": {
        "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
        "type": "pickup"
      },
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "date": "20220223",
      "isApproved": true,
      "displayLabel": "1.1"
    },
    {
     "orderStepId": {
        "orderId": "7a433c07-a605-4684-b785-4a7568b6401b",
        "type": "delivery"
      },
      "vehicleId": "492c1f4b-467d-4349-ae0a-0947f0baa4da",
      "driverId": "cb482f01-d52e-4322-bac2-ddb78f0f2bec",
      "date": "20220223",
      "isApproved": true,
      "displayLabel": "1.3"
    },
    {
      "orderStepId": {
        "orderId": "11afce76-27aa-43c8-8b9b-cd0a2b6b937b",
        "type": "delivery"
      },
      "isApproved": false
    }
  ],
  "trackingData": {
    "delivery-0db3c44e-cfa1-4cd5-853d-57749cc3632e": {
      "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
      "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
      "timeInSec": -1,
      "timeInLatLng": null,
      "timeOutSec": 7200,
      "timeOutLatLng": [
        45000435,
        8106819
      ],
      "status": "done",
      "statusSec": 7200,
      "statusLatLng": [
        45000435,
        8106819
      ],
      "statusReason": null,
      "timeInDetectedSec": -1,
      "timeInDetectedLatLng": null,
      "timeOutDetectedSec": -1,
      "timeOutDetectedLatLng": null,
      "pods": null
    },
    "delivery-7a433c07-a605-4684-b785-4a7568b6401b": null,
    "delivery-11afce76-27aa-43c8-8b9b-cd0a2b6b937b": null
  }
}

Notifies that some OrderSteps TrackingData has changed.

This can be the result of an execution Event sent from mobile or via API request, or a manual operation performed via the Web Application.

In general, any operation that updates the TrackingData of an OrderStep will trigger this WebHook notification.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the OrderStep tracking data changed case must be “ORDER_STEP_TRACKING_DATA_UPDATED”
assignments list of OrderStepAssignment Informations regarding the assignment of the OrderStep(s)
trackingData map[String]TrackingData A map where the key is composed by the OrderStepId in the form of type-OrderId, and the value is the associated Tracking Data

Depots Notification

Changes to a depot triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "DEPOT_ADDED",
  "depots": {
    "842f2b06-73f8-4bd3-814e-94e054611481": {
      "id": "842f2b06-73f8-4bd3-814e-94e054611481",
      "name": "Test Depot",
      "setupCost": 10000,
      "setupTimeSec": 3600,
      "location": {
        "address": "47A E 7th St, New York, NY 10003, USA",
        "latLng": [
          40727832,
          -73987819
        ],
        "status": "OK",
        "geoAddress": "47A E 7th St, New York, NY 10003, USA"
      },
      "color": "004ACC"
    }
  }
}

Notifies that some Depots’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Depots API or of a manual operation performed via the Web Application.

In general, any operation that changes Depots’ data (create/update/delete) triggers a WebHook notification that contains the new Depot information.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the depot changed case can be “DEPOT_ADDED”, “DEPOT_UPDATED” or “DEPOT_DELETED”
depots map[UUID]Depot A map where the key is the Depot Id and the value is the associated Depot Object

Driver Notification

Changes to a driver triggers a notification structured like this:

{
  "apiRequestId": null,
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "DRIVER_UPDATED",
  "drivers": {
    "211d328f-ffaa-449c-ae87-80dec69ce14f": {
      "id": "211d328f-ffaa-449c-ae87-80dec69ce14f",
      "name": "Test Driver",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "test@workwave.com",
      "gpsDeviceId": null
    }
  }
}

Notifies that some Drivers’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Driver API or of a manual operation performed via the Web Application.

In general, any operation that changes Drivers’ data (create/update/delete) triggers a WebHook notification that contains the new Driver information.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.
eventType String The event that triggered the webhook. In the driver changed case can be “DRIVER_ADDED”, “DRIVER_UPDATED” or “DRIVER_DELETED”
drivers map[UUID]Driver A map where the key is the driverId and the value is the associated Driver object

Region Notification

Changes to a region triggers a notification structured like this:

{
  "apiRequestId": "bee1d28f-d0a8-4026-99a0-962562f808f1",
  "territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
  "timeZoneCode": "America/New_York",
  "eventType": "REGION_DELETED",
  "regions": {
    "f1503235-e65e-4efd-83fd-a2c8a9e7f82b": {
      "id": "f1503235-e65e-4efd-83fd-a2c8a9e7f82b",
      "name": "Test Region",
      "color": "6633CC",
      "poly": [
        [ 40759224, -74005155 ],
        [ 40747521, -73968248 ],
        [ 40713960, -73976316 ],
        [ 40721376, -74012022 ],
        [ 40740627, -74010220 ]
        ]
      ],
      "enterCost": 1000,
      "enterTimeSec": 1800
    }
  }
}

Notifies that some Regions’ data has changed.

This can be the result of an asynchronous API request such as the ones described at Region API or of a manual operation performed via the Web Application.

In general, any operation that changes Regions’ data (create/update/delete) triggers a WebHook notification that contains the new Region information.

RETURN VALUES

Property Type Description
apiRequestId String OR null Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI)
territoryId UUID Territory ID
timeZoneCode String TimeZone code for the territory
username String The username of the user who initiated the triggering event. If the event was triggered by an API request, no username will be provided, as there is no associated user.
isApiRequest boolean States whether the source of the triggering event is from the API or the UI.\
eventType String The event that triggered the webhook. In the region changed case can be “REGION_ADDED”, “REGION_UPDATED” or “REGION_DELETED”
regions map[UUID]Region A map where the key is the regionId and the value is the associated Region object

Object Definitions

Territory objects

Territory Object properties

{
  "id": "4cf132f2-e0bc-4a1b-a167-a4b80056690c",
  "name": "New York",
  "center": [40737716, -73988150],
  "timeZoneCode": "America/New_York",
  "languageCode": "en",
  "statusReasons": ["Absent recipient"],
  "borderRestrictionCountryCode": null
}
Property Type Description
id UUID Globally Unique Territory ID
name String Territory’s name
center LatLng Territory’s center coordinates
timeZoneCode String List of time zones in the tz database
E.g.: America/New_York, Europe/Rome
languageCode String IETF language tag
E.g.: en, en-US, pt-BR
statusReasons list of String List of the allowed reasons (also used by the mobile application) to provide more details about a not completed (with the related status set to reschedule) step
borderRestrictionCountryCode String Country name and country code for the Border Restrction feature. If enabled, the format is Country Name (Country Code), null otherwise

Depot objects

DepotInput Object properties

{
  "name": "Depot A",
  "setupCost": 1000,
  "setupTimeSec": 1800,
  "location": {
    "address": "320 20th St W, Jasper, AL 35501, USA",
    "latLng": [
      33831316,
      -87278355
    ],
    "status": "OK"
  },
  "color": "998800"
}
Property Type Description
name String Depot’s name
location Location Depot’s location
setupCost int Cost that is factored in every time the Vehicle goes back to this Depot to reload.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
setupTimeSec int Setup time in seconds that is factored in every time the Vehicle goes back to this Depot to reload
color String Depot’s color in RGB hex format (e.g.: FFA0C3)

Depot Object properties

{
  "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "name": "Depot A",
  "setupCost": 1000,
  "setupTimeSec": 1800,
  "location": {
    "address": "320 20th St W, Jasper, AL 35501, USA",
    "latLng": [
      33831316,
      -87278355
    ],
    "status": "OK"
  },
  "color": "998800"
}
Property Type Description
id UUID Unique (per-territory) Depot ID
name String Depot’s name
location Location Depot’s location
setupCost int Cost that is factored in every time the Vehicle goes back to this Depot to reload.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
setupTimeSec int Setup time in seconds that is factored in every time the Vehicle goes back to this Depot to reload
color String Depot’s color in RGB hex format (e.g.: FFA0C3)

DepotUpdate Object properties

{
  "id": "8cc0a631-dd54-4782-b368-274cfb6dd836",
  "name": "Depot ABC",
  "color": "99FF88"
}
Property Type Description
id UUID Unique (per-territory) Depot ID
name String Depot’s name
color String Depot’s color in RGB hex format (e.g.: FFA0C3)

DepotsChanged Object properties

{
  "created": [
    "d734a903-79a0-45df-ab0d-cf9573cd5f45"
  ],
  "updated": [
    "662ed6b6-bcc2-4cfb-b5e4-18e52899a033"
  ],
  "deleted": [
    "aebeaebb-8e1f-4135-89a7-fee744163f20"
  ]
}
Property Type Description
created list of UUID UUIDs of created Depots
updated list of UUID UUIDs of updated Depots
deleted list of UUID UUIDs of deleted Depots

Region objects

RegionInput Object properties

{
  "name": "South Jasper",
  "color": "2E5984",
  "poly": [
    [33840336, -87319165],
    [33839766, -87220803],
    [33794127, -87229386],
    [33792558, -87245007],
    [33812528, -87259598],
    [33812956, -87305947],
    [33812956, -87325860]
  ],
  "enterCost": 2000,
  "enterTimeSec": 1200
}
Property Type Description
name String Region’s name
color String Region’s color in RGB hex format (e.g.: FFA0C3)
poly list of LatLng List of locations defining a valid (non-collinear, non-self-intersecting) polygon
enterCost int Cost in cents that is factored in every time a Vehicle moves from a location that is outside of this Region to an Order that is within this Region.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
enterTimeSec int Time in seconds that is added to the driving time every time the vehicle drives from a location that is outside of this Region to an Order that is within this Region

Region Object properties

{
  "id": "ddcbe348-5b4d-483d-9d6c-1b149120ca7e",
  "name": "South Jasper",
  "color": "2E5984",
  "poly": [
    [33840336, -87319165],
    [33839766, -87220803],
    [33794127, -87229386],
    [33792558, -87245007],
    [33812528, -87259598],
    [33812956, -87305947],
    [33812956, -87325860]
  ],
  "enterCost": 2000,
  "enterTimeSec": 1200
}
Property Type Description
id UUID Unique (per-territory) Region ID
name String Region’s name
color String Region’s color in RGB hex format (e.g.: FFA0C3)
poly list of LatLng List of locations defining a valid (non-collinear, non-self-intersecting) polygon
enterCost int Cost in cents that is factored in every time a Vehicle moves from a location that is outside of this Region to an Order that is within this Region.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
enterTimeSec int Time in seconds that is added to the driving time every time the vehicle drives from a location that is outside of this Region to an Order that is within this Region

Vehicle objects

Vehicle Object properties

{
  "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "idx": 1,
  "externalId": "Vehicle 1",
  "color": "009944",
  "tracked": true,
  "sameSideOfStreet": false,
  "gpsDeviceId": "40519",
  "settings": {
    "available": true,
    "notes": "",
    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "timeWindow": {
      "startSec": 28800,
      "endSec": 61200
    },
    "flexStartTime": true,
    "perStopCost": 0,
    "perStopTimeSec": 0,
    "maxWorkingTimeSec": 0,
    "maxDrivingTimeSec": 0,
    "maxDistanceMt": 0,
    "maxOrders": 0,
    "maxLocations": 0,
    "maxStops": 0,
    "breaks": [],
    "loadCapacities": {
      "frozen ton": 500,
      "regular ton": 500
    },
    "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
    "activationCost": 0,
    "drivingTimeCost": 2000,
    "idleTimeCost": 2000,
    "serviceTimeCost": 2000,
    "breakTimeCost": 2000,
    "kmCost": 100,
    "tags": [
      "frozen",
      "regular"
    ],
    "speedFactor": 100,
    "minWorkingTimeSec": 0,
    "minLoadCapacities": {},
    "preparationTimeSec": 600,
    "closeOutTimeSec": 0
  }
}
Property Type Description
id UUID Unique (per-territory) Vehicle ID
idx int Unique (per-territory) numeric index associated to the Vehicle (used for display purposes when setting displayLabel)
externalId String Unique (per-territory) external ID associated to the Vehicle
color String Vehicle’s color in RGB hex format (e.g.: FFA0C3),
tracked boolean true if the vehicle is tracked via a mobile application, false otherwise
sameSideOfStreet boolean Default false, enable the Same Side of Street feature for the Vehicle
gpsDeviceId String The GPS device id associated with this Vehicle (see List GPS Devices). Set to null if any of the following is true:
  • no GPS Device is associated
  • no tracking provider is selected for the account
  • the Vehicle is tracked via the RouteManager Mobile App
settings VehicleSettings Normal day VehicleSettings of the Vehicle

VehicleFull Object properties

{
  "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "idx": 1,
  "externalId": "Vehicle 1",
  "color": "009944",
  "tracked": true,
  "sameSideOfStreet": true,
  "gpsDeviceId": null,
  "settings": {
    "20151203": {
      "available": true,
      "notes": "",
      "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "timeWindow": {
        "startSec": 28800,
        "endSec": 61200
      },
      "flexStartTime": true,
      "perStopCost": 0,
      "perStopTimeSec": 0,
      "maxWorkingTimeSec": 0,
      "maxDrivingTimeSec": 0,
      "maxDistanceMt": 0,
      "maxOrders": 0,
      "breaks": [],
      "loadCapacities": {
        "frozen ton": 500,
        "regular ton": 500
      },
      "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
      "activationCost": 0,
      "drivingTimeCost": 2000,
      "idleTimeCost": 2000,
      "serviceTimeCost": 2000,
      "breakTimeCost": 2000,
      "kmCost": 100,
      "tags": [
        "frozen",
        "regular"
      ],
      "speedFactor": 100,
      "minWorkingTimeSec": 0,
      "minLoadCapacities": {},
      "preparationTimeSec": 600,
      "closeOutTimeSec": 0
    },
    "20151204": { ... }, // more settings for 2015-12-04
    ...                  // more settings for more dates
  }
}
Property Type Description
id UUID Unique (per-territory) Vehicle ID
idx int Unique (per-territory) numeric index associated to the Vehicle (used for display purposes when setting displayLabel)
externalId String Unique (per-territory) external ID associated to the Vehicle
color String Vehicle’s color in RGB hex format (e.g.: FFA0C3)
tracked boolean True if the vehicle is tracked via a mobile application, false otherwise
sameSideOfStreet boolean Default false, enable the Same Side of Street feature for the Vehicle
gpsDeviceId String The GPS device id associated with this Vehicle (see List GPS Devices). Set to null if any of the following is true:
  • no GPS Device is associated
  • no tracking provider is selected for the account
  • the Vehicle is tracked via the RouteManager Mobile App
settings map[DateString] VehicleSettings Maps a date to additional date-related settings

VehicleSettings Object properties

{
  "available": true,
  "notes": "",
  "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
  "timeWindow": {
    "startSec": 28800,
    "endSec": 61200
  },
  "flexStartTime": true,
  "perStopCost": 0,
  "perStopTimeSec": 0,
  "maxWorkingTimeSec": 0,
  "maxDrivingTimeSec": 0,
  "maxDistanceMt": 0,
  "maxOrders": 0,
  "maxLocations": 0,
  "maxStops": 0,
  "breaks": [],
  "loadCapacities": {
    "frozen ton": 500,
    "regular ton": 500
  },
  "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
  "activationCost": 0,
  "drivingTimeCost": 2000,
  "idleTimeCost": 2000,
  "serviceTimeCost": 2000,
  "breakTimeCost": 2000,
  "kmCost": 100,
  "tags": [
    "frozen",
    "regular"
  ],
  "speedFactor": 100,
  "minWorkingTimeSec": 0,
  "minLoadCapacities": {},
  "preparationTimeSec": 600,
  "closeOutTimeSec": 0
}
Property Type Description
available boolean True if the Vehicle (or Driver) is available to drive on this date, false otherwise
notes String Account-owner-entered notes for this date
departureDepotId UUID OR null ID of the departure depot, or null if the Vehicle’s departure location is the first visited Order (aka: open-start)
arrivalDepotId UUID OR null ID of the arrival depot, or null if the Vehicle does not have to return to any specific end destination (aka: open-end or open-route)
timeWindow TimeWindow OR null The Vehicle (or Driver) working time window on this date
flexStartTime boolean If false forces the vehicle to leave its departure depot at the beginning of its working time window, otherwise the vehicle can be scheduled to leave at a later time if that reduces the overall costs
perStopCost int Cost in cents that is factored in every time the vehicle stops at a different place, depots excluded.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
perStopTimeSec int Time in seconds that is factored in every time the vehicle stops at a different place, depots excluded (e.g.: average parking time).
LIMITS: must range between 0 and 86400 (24 hours).
maxWorkingTimeSec int Maximum allowed working time, in seconds (includes driving time, idle time, service time and break time). Zero means no limit.
LIMITS: must range between 0 and 86400 (24 hours).
maxDrivingTimeSec int Maximum allowed driving time, in seconds. Zero means no limit.
LIMITS: must range between 0 and 86400 (24 hours).
maxDistanceMt int Maximum allowed driving distance, in meters. Zero means no limit.
LIMITS: must be >= 0.
maxOrders int Maximum number of served Orders. Zero means no limit.
Note that an Order defining both pickup and delivery steps still counts as one (1).
LIMITS: must be >= 0.
maxLocations int Maximum number of visited locations. If the same location is visited twice, it’s counted as a single visit. Zero means no limit.
LIMITS: must be >= 0.
maxStops int Maximum number of stops that a vehicle can make. If the same location is is visited twice or more not consecutive times, the visits are considered two or more different stops (one stop for each not consecutive visit). Zero means no limit.
LIMITS: must be >= 0.
breaks list of Break Driver breaks.
LIMITS: cannot contain more than 3 Breaks.
Multiple breaks cannot overlap each other and overlapping takes break duration into account.
For overlap-checking consider a break as starting at its startSec and ending at endSec+durationSec, inclusive.
E.g.: a 1 hour break starting between 1pm and 2pm can potentially be scheduled at 2pm therefore extending up to 3pm, so it can overlap a second break set between 2.30pm and 3.30pm.
loadCapacities map[String]int Maximum load allowances.
IMPORTANT: only lowercase is accepted for load keys. All uppercase characters are automatically and silently lowercased on import
LIMITS: each VehicleSettings cannot contain more than 20 load items (different VehicleSettings can still contain different sets of up to 20 items).
The string identifying a load key cannot be empty nor longer than 30 characters.
Load values must be integers ranging between 0 and 1_000_000_000, inclusive.
Note: the values of the map represent decimal numbers. The values will be divided by 100. E.g.: 123 means 1.23
regionIds list of UUID UUID of Regions associated to this Vehicle on this date
activationCost int Cost that must be factored in if this Vehicle is used. In cents.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
drivingTimeCost int In cents per hour.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
idleTimeCost int In cents per hour.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
serviceTimeCost int In cents per hour.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
breakTimeCost int In cents per hour.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
kmCost int In cents per kilometer.
LIMITS: must range between 0 and 100_000_000, inclusive.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
tags list of String Tags are referenced by OrderSteps’ tagsIn and tagsOut properties to restrict vehicle-order assignments. See OrderStep properties for more details.
IMPORTANT: only lowercase is accepted. All uppercase characters are automatically and silently lowercased on import
LIMITS: cannot contain more than 50 items. In case you need more, please contact Support Team. Each item cannot be longer than 50 characters.
speedFactor int Relative average vehicle speed in percent. Ranges between 50% and 200%. Defaults to 100%
minWorkingTimeSec int Minimum requirement for working time, in seconds (includes driving time, idle time, service time and break time). Zero means no minimum requirement.
LIMITS: must range between 0 and 86400 (24 hours).
NOTE: we will try to come as close as possible to these requirement, but it may not be met 100%.
minLoadCapacities map[String]int Minimum requirement for loads.
IMPORTANT: only lowercase is accepted for load keys. All uppercase characters are automatically and silently lowercased on import
LIMITS: each cannot contain more than 20 load items (different VehicleSettings can still contain different sets of up to 20 items).
The string identifying a load key cannot be empty nor longer than 30 characters.
Load values must be integers ranging between 0 and 1_000_000_000, inclusive.
NOTE: we will try to come as close as possible to these requirement, but it may not be met 100%.
Note: the values of the map represent decimal numbers. The values will be divided by 100. E.g.: 123 means 1.23
preparationTimeSec int Time needed to prepare the vehicle at the beginning of the route. Default to 0. Can be set only if departureDepotId is not null
closeOutTimeSec int Time needed to settle the vehicle at the end of the route. Default to 0. Can be set only if arrivalDepotId is not null

VehicleInput Object properties

{
  "externalId": "New Vehicle #1",
  "color": "c08e88",
  "tracked": true,
  "sameSideOfStreet": true,
  "gpsDeviceId": null,
  "settings": {
    "available": true,
    "notes": "Vehicle added via REST API",
    "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
    "timeWindow": {
      "startSec": 28800,
      "endSec": 61200
    },
    "flexStartTime": true,
    "perStopCost": 0,
    "perStopTimeSec": 0,
    "maxWorkingTimeSec": 0,
    "maxDrivingTimeSec": 0,
    "maxDistanceMt": 0,
    "maxOrders": 0,
    "breaks": [],
    "loadCapacities": {
      "people": 1500
    },
    "regionIds": [],
    "activationCost": 10000,
    "drivingTimeCost": 2000,
    "idleTimeCost": 2000,
    "serviceTimeCost": 2000,
    "breakTimeCost": 2000,
    "kmCost": 100,
    "tags": [
      "light"
    ],
    "speedFactor": 130,
    "minWorkingTimeSec": 0,
    "minLoadCapacities": {},
    "preparationTimeSec": 600,
    "closeOutTimeSec": 0
  }
}
Property Type Description
externalId String Unique (per-territory) external ID associated to the Vehicle
color String Vehicle’s color in RGB hex format (e.g.: FFA0C3)
tracked boolean True if the vehicle is tracked via a mobile application, false otherwise
sameSideOfStreet boolean Default false, enable the Same Side of Street feature for the Vehicle
gpsDeviceId String The GPS device id associated with this Vehicle (see List GPS Devices). Set to null if any of the following is true:
  • no GPS Device is associated
  • no tracking provider is selected for the account
  • the Vehicle is tracked via the RouteManager Mobile App
settings VehicleSettings Default VehicleSettings for the new Vehicle

VehicleDetails Object properties

{
  "id": "a3935987-4944-462f-b602-4a3a12beeeff",
  "externalId": "New Vehicle #1",
  "color": "c08e88",
  "tracked": true,
  "sameSideOfStreet": true,
  "gpsDeviceId": null
}
Property Type Description
id String Unique Vehicle ID
externalId String Unique (per-territory) external ID associated to the Vehicle
color String Vehicle’s color in RGB hex format (e.g.: FFA0C3)
tracked boolean True if the vehicle is tracked via a mobile application, false otherwise
sameSideOfStreet boolean Enable the Same Side of Street feature for the Vehicle
gpsDeviceId String The GPS device id associated with this Vehicle (see List GPS Devices). Set to null if any of the following is true:
  • no GPS Device is associated
  • no tracking provider is selected for the account
  • the Vehicle is tracked via the RouteManager Mobile App

Driver objects

Driver Object properties

{
  "id": "a3935987-4944-462f-b602-4a3a12beeeff",
  "name": "Driver 1",
  "email": "driver1@example.com",
  "summarizeFutureMobileRoute": true,
  "mobileFutureDaysVisibility": 2,
  "gpsDeviceId": "57290"
}
Property Type Description
id UUID Unique Driver ID
name String Driver name
email String Driver email
summarizeFutureMobileRoute boolean Default false. Defines the behavior while using the Mobile App. If true the routes for future dates will be summarized. If false the routes will appear complete. A summarized route shows only the first step, the last step, and the number of orders in between, without the detailed order list.
mobileFutureDaysVisibility int Default 2. Indicates how many days in the future the mobile app will show. Possible values are 2 or -1. If -1 it will show all dispatchable days. When listing the driver, the -1 will be substitute with the correct value.
gpsDeviceId String The GPS device id associated to this Driver. null if either no GPS device is associated or no WorkWave GPS account is connected

DriverInput Object properties

{
  "name": "Driver 3",
  "email": "driver3@example.com",
  "password": "PhQ?Hqrt$4bs6_^2",
  "summarizeFutureMobileRoute": false,
  "mobileFutureDaysVisibility": 2,
  "gpsDeviceId": null
}
Property Type Description
name String Driver name
email String Driver email
password String Driver password
summarizeFutureMobileRoute boolean Default false. Defines the behavior while using the Mobile App. If true the routes for future dates will be summarized. If false the routes will appear complete. A summarized route shows only the first step, the last step, and the number of orders in between, without the detailed order list.
mobileFutureDaysVisibility int Default 2. Indicates how many days in the future the mobile app will show. Possible values are 2 or -1. If -1 it will show all dispatchable days. When listing the driver, the -1 will be substitute with the correct value.
gpsDeviceId String Optional: a GPS device id provisioned with category “MOBILE”.
IMPORTANT: requires a connected WorkWave GPS account. Must be omitted or set to null otherwise.

Company objects

Company Object properties

{
  "id": "0c920b8e-e904-444c-8371-63cd62f5b1bb",
  "name": "ACME Corp",
  "enabled": true
}
Property Type Description
id String Company ID
name String Company name
enabled boolean true if the company is enabled (can be assigned to orders or users), false otherwise

CompanyInput Object properties

{
  "name": "ACME Corp",
  "enabled": true
}
Property Type Description
name String Company name for the new/updated company (must be unique)
enabled boolean true if the company is enabled (can be assigned to orders or users), false otherwise

Order objects

Order Object properties

{
  "id": "49269a16-479c-4531-8ffd-513b7ccd0621",
  "name": "Order 1",
  "eligibility": {
    "type": "on",
    "onDates": [
      "20151204",
      "20151205",
      "20151206"
    ]
  },
  "forceVehicleId": null,
  "priority": 0,
  "loads": {},
  "pickup": null,
  "delivery": {
    "depotId": null,
    "location": {
      "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
      "latLng": [
        33817872,
        -87266893
      ],
      "status": "OK"
    },
    "timeWindows": [
      {
        "startSec": 30600,
        "endSec": 37800
      },
      {
        "startSec": 45000,
        "endSec": 55800
      }
    ],
    "notes": "demonstrate the concept of multiple time windows as well as eligibility date range",
    "email": "mail@companyname.com",
    "phone": "+18007620301",
    "serviceTimeSec": 600,
    "tagsIn": [],
    "tagsOut": [],
    "customFields": {}
  },
  "isService": false,
  "companyId": null
}
Property Type Description
id UUID Unique (per-territory) Order ID
name String Name of the Order, for visualization purposes only
eligibility Eligibility On what dates the Order is eligible to be serviced
forceVehicleId UUID OR null The id of the Vehicle that has been forcefully assigned to service this Order, if any
priority int Allowed values: -20,-10,0,10,20 where 0 is for normal priority and 20 is highest
loads map[String]int A map where the key is the load (e.g.: kgs, pounds, m3, etc) and the value is the quantity.
Note: the values of the map represent decimal numbers. The values will be divided by 100. E.g.: 123 means 1.23
pickup OrderStep OR null The pickup part of this Order, where applicable. null when isService = true
delivery OrderStep OR null The delivery part of the Order, where applicable. Set when isService = true
isService boolean True if this is a “service” Order. Service Orders are represented as “delivery” Orders with no loads.
Note: as a result, “service” Orders will show up with type = “delivery” when referenced in RouteSteps or OrderStepIdentifiers
companyId UUID or null The id of the Company related to the Order (if any). Guest Users set on the UI to be filtered by company can access only the orders provided with a companyId related to one of the companies associated with them.
Note: in case the Company is deleted, the field is not automatically updated, so it could refers also a not-existing company. In this case, the behavior is considered the same of a null companyId (so no User filtered by company will be able to access it)
Note: if provided and not null, in case of a new/replaced order, it must be related to an enabled company

OrderInput Object properties

{
  "name": "Added Order",
  "eligibility": {
    "type": "on",
    "onDates": [
      "20151204",
      "20151205",
      "20151206"
    ]
  },
  "forceVehicleId": null,
  "priority": 0,
  "loads": {
    "pounds": 5000,
    "cubic inches": 4500
  },
  "pickup": null,
  "delivery": {
    "depotId": null,
    "location": {
      "address": "3101 Florida Ave, Jasper, AL 35501, USA"
    },
    "timeWindows": [
      {
        "startSec": 30600,
        "endSec": 37800
      },
      {
        "startSec": 45000,
        "endSec": 55800
      }
    ],
    "notes": "deliver and connect equipment on site",
    "email": "mail@companyname.com",
    "phone": "+18007620301",
    "serviceTimeSec": 600,
    "tagsIn": [
      "plumbing skills",
      "power tools"
    ],
    "tagsOut": [
      "large vehicle"
    ],
    "customFields": {
      "OrderID": "XDTG-14356",
      "PIN": "1234"
    }
  },
  "isService": false,
  "acceptBadGeocodes": true,
  "companyId": null
}
Property Type Description
name String Name of the Order, for visualization purposes only.
LIMITS: limited to 100 characters. Longer names will be truncated.
eligibility Eligibility On what dates the Order is eligible to be serviced.
LIMITS: dates cannot be in the past nor exceed the allowed maximum horizon.
forceVehicleId UUID OR null Optional. Set to null to let the system select the best Vehicle
priority int Allowed values: -20,-10,0,10,20 where 0 is for normal priority and 20 is highest
loads map[String]int A map where the key is the load (e.g.: kgs, pounds, m3, etc) and the value is the quantity.
IMPORTANT: only lowercase is accepted for load keys. All uppercase characters are automatically and silently lowercased on import
LIMITS: each Order cannot contain more than 10 load items (different Orders can still contain different sets of up to 10 items).
The string identifying a load key cannot be empty nor longer than 30 characters.
Load values must be integers ranging between 0 and 1_000_000_000, inclusive.
Note: the values of the map represent decimal numbers. The values will be divided by 100. E.g.: 123 means 1.23
pickup OrderStepInput The pickup part of this Order, where applicable. Must be null if isService = true
delivery OrderStepInput The delivery part of the Order, where applicable. Must be set if isService = true
isService boolean Optional, defaults to false. Let the UI know that this order should be presented as a “service” one.Service Orders are actually “delivery” Orders with no loads.
Note: as a result, “service” Orders will show up with type = “delivery” when referenced in RouteSteps
acceptBadGeocodes boolean Optional, defaults to false.

Note: this parameter is used only in the Replace an Order and the Update an Order APIs, ignored otherwise.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.
companyId UUID or null Optional. The id of the Company related to the Order (if any). Guest Users set on the UI to be filtered by company can access only the orders provided with a companyId related to one of the companies associated with them.
Note: if not null, it must be related to an enabled company

OrderStep Object properties

{
  "depotId": null,
  "location": {
    "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
    "latLng": [
      33817872,
      -87266893
    ],
    "status": "OK"
  },
  "timeWindows": [
    {
      "startSec": 30600,
      "endSec": 37800
    },
    {
      "startSec": 45000,
      "endSec": 55800
    }
  ],
  "timeWindowExceptions": {
    "20151205": [
      {
        "startSec": 64800,
        "endSec": 68400
      }
    ],
    "20151206": [
      {
        "startSec": 30600,
        "endSec": 37800
      },
      {
        "startSec": 61200,
        "endSec": 64800
      }
    ]
  },
  "notes": "deliver and connect equipment on site",
  "email": "mail@companyname.com",
  "phone": "+18007620301",
  "serviceTimeSec": 600,
  "tagsIn": [
    "plumbing skills",
    "power tools"
  ],
  "tagsOut": [
    "large vehicle"
  ],
  "customFields": {
    "OrderID": "XDTG-14356",
    "PIN": "1234"
  },
  "barcodes": [
    "1234567891234"
  ]
}
Property Type Description
depotId UUID OR null Depot Id. Only set if the OrderStep’s location is at a Depot, null otherwise
location Location OR null Order’s location, null if this OrderStep is located at a Depot
timeWindows list of TimeWindow When the OrderStep can be serviced during each eligible day
timeWindowExceptions map[DateString] list of TimeWindow Overrides timeWindows on specific dates
notes String Order notes. For visualization purposes only
email String Contact email related to the OrderStep. Used for final customer notification purpose. Formally not valid email addresses are always accepted, but the notifications will not be delivered to those addresses. The validation result is available into the asynchronous notification object ChangedOrder when the OrderStep is created/updated.
phone String Contact phone related to the OrderStep. Used for final customer notification purpose. Formally not valid phone numbers are always accepted, but the notifications will not be delivered to those numbers. The validation result is available into the asynchronous notification object ChangedOrder when the OrderStep is created/updated.
serviceTimeSec int Expected service time in seconds
tagsIn list of String A list of tags that a Vehicle must define to be able to service this OrderStep.
LIMITS: cannot contain more than 50 items. In case you need more, please contact Support Team. Each item cannot be longer than 50 characters.
tagsOut list of String Vehicles defining one or more of these tags cannot service this OrderStep.
LIMITS: cannot contain more than 50 items. In case you need more, please contact Support Team. Each item cannot be longer than 50 characters.
customFields map[String]String Custom fields associated to this OrderStep. For visualization purposes only
barcodes list of String A list of barcodes.

OrderStepInput Object properties

{
  "depotId": null,
  "location": {
    "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
  },
  "timeWindows": [
    {
      "startSec": 30600,
      "endSec": 37800
    },
    {
      "startSec": 45000,
      "endSec": 55800
    }
  ],
  "timeWindowExceptions": {
    "20151205": [
      {
        "startSec": 64800,
        "endSec": 68400
      }
    ],
    "20151206": [
      {
        "startSec": 30600,
        "endSec": 37800
      },
      {
        "startSec": 61200,
        "endSec": 64800
      }
    ]
  },
  "notes": "deliver and connect equipment on site",
  "email": "mail@companyname.com",
  "phone": "+18007620301",
  "serviceTimeSec": 600,
  "tagsIn": [
    "plumbing skills",
    "power tools"
  ],
  "tagsOut": [
    "large vehicle"
  ],
  "customFields": {
    "OrderID": "XDTG-14356",
    "PIN": "1234"
  },
  "barcodes": [
    "1234567891234"
  ],
  "acceptBadGeocodes": true
}
Property Type Description
depotId UUID OR null Depot Id (if the OrderStep’s location is at a Depot)
Note: Only one of “depotId” and “location” can be specified
location LocationInput OR null Order’s location (if the OrderStep does not coincide with a Depot)
Note: Only one of “depotId” and “location” can be specified
timeWindows list of TimeWindow When the OrderStep can be serviced during each eligible day.
LIMITS: cannot contain more than 4 TimeWindows.
timeWindowExceptions map[DateString] list of TimeWindow Allows overriding timeWindows on specific dates.
LIMITS: cannot contain more than 3 dates, where each date cannot reference more than 4 TimeWindows.
Specified dates must match the Order’s eligibility range
notes String Notes.
LIMITS: limited to 1500 characters. Longer notes will be truncated.
email String Contact email related to the OrderStep. Used for final customer notification purpose. Formally not valid email addresses are always accepted, but the notifications will not be delivered to those addresses. The validation result is available into the asynchronous notification object ChangedOrder when the OrderStep is created/updated.
phone String Contact phone related to the OrderStep. Used for final customer notification purpose. Formally not valid phone numbers are always accepted, but the notifications will not be delivered to those numbers. The validation result is available into the asynchronous notification object ChangedOrder when the OrderStep is created/updated.
serviceTimeSec int Expected service time in seconds.
LIMITS: must range between 0 and 86400 (24 hours).
tagsIn list of String A list of tags that a Vehicle must define to be able to service this OrderStep.
IMPORTANT: only lowercase is accepted. All uppercase characters are automatically and silently lowercased on import
LIMITS: cannot contain more than 50 items. In case you need more, please contact Support Team. Each item cannot be longer than 50 characters.
tagsOut list of String Vehicles defining one or more of these tags cannot service this OrderStep.
IMPORTANT: only lowercase is accepted. All uppercase characters are automatically and silently lowercased on import
LIMITS: cannot contain more than 50 items. In case you need more, please contact Support Team. Each item cannot be longer than 50 characters.
customFields map[String]String Custom fields associated to this OrderStep. For visualization purposes only.
LIMITS: each OrderStep cannot contain more than 20 custom fields (different OrderSteps can still contain different sets of up to 20 items).
The string identifying a custom field key cannot be empty nor longer than 50 characters.
The total combined size of all custom field values cannot exceed 3000 characters.
barcodes list of String Optional. A list of barcodes.
LIMITS: by default, each OrderStep cannot have more than 10 barcodes. If you need more, please contact our support. Each barcode can be at maximum 100 characters long and cannot contain commas. The same barcode can be repeaded multiple times.
acceptBadGeocodes boolean Optional, defaults to false.

Note: this parameter is used only in the Replace an OrderStep API, ignored otherwise.

When set to false Orders that cannot be geocoded (i.e.: either the address is unknown OR the geocoded coordinates fall outside of the territory range) are skipped.

Note: the “unknown addresses” mentioned above do NOT include addresses that are geocoded correctly but with a “low-accuracy” location. Orders with valid but low-accuracy addresses will be accepted; e.g., abcd, Brooklyn, NY, 00000 is considered low-accuracy but valid nonetheless.

When set to true all Orders are updated regardless of geocoding issues. In that case it will be possible to review and fix them manually from the Web Application.
IMPORTANT: When acceptBadGeocodes is true Orders that fail to be geocoded and have missing or invalid coordinates will be ignored by Build Routes and Fit-In requests.
If the updated Order has an invalid location and it is scheduled within a Route, however, the Order update is skipped regardless of the acceptBadGeocodes flag value.

Route objects

Route Object properties

{
  "id": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
  "revision": 182,
  "date": "20151204",
  "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
  "vehicleViolations": ["LD", "ML", "TWE"],
  "steps": [
    {
      "type": "departure",
      "idleTimeSec": 0,
      "perStopTimeSec": 0,
      "arrivalSec": 0,
      "startSec": 0,
      "endSec": 32329,
      "driveToNextSec": -1,
      "distanceToNextMt": -1,
      "stopIdx": 0,
      "displayLabel": "",
      "trackingLink": "https://l-nk.io/xZv4ARF"
    },
    {
      "type": "delivery",
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "idleTimeSec": 0,
      "perStopTimeSec": 0,
      "arrivalSec": 34200,
      "startSec": 34200,
      "endSec": 36000,
      "driveToNextSec": -1,
      "distanceToNextMt": -1,
      "stopIdx": 1,
      "displayLabel": "1.1",
      "violations": ["TGI", "TW"],
      "trackingData": {
        "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
        "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
        "timeInSec": 34526,
        "timeInLatLng": [
          33817872,
          -87266893
        ],
        "timeOutSec": -1,
        "timeOutLatLng": null,
        "status": "done",
        "statusSec": 35912,
        "statusLatLng": [
          33817872,
          -87266893
        ],
        "statusReason": null,
        "timeInDetectedSec": 34201,
        "timeInDetectedLatLng": [
          33817942,
          -87266921
        ],
        "timeOutDetectedSec": 35935,
        "timeOutDetectedLatLng": [
          33817404,
          -87266657
        ]
      }
    },
    {
      "type": "pickup",
      "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
      "idleTimeSec": 0,
      "perStopTimeSec": 0,
      "arrivalSec": 39600,
      "startSec": 39600,
      "endSec": 40600,
      "driveToNextSec": -1,
      "distanceToNextMt": -1,
      "stopIdx": 2,
      "displayLabel": "1.2",
      "trackingData": {
        "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
        "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
        "timeInSec": 39600,
        "timeInLatLng": [
          33480873,
          -86788220
        ],
        "timeOutSec": 40720,
        "timeOutLatLng": [
          33480873,
          -86788220
        ],
        "status": "done",
        "statusSec": 40780,
        "statusLatLng": [
          33480873,
          -86788220
        ],
        "statusReason": null,
        "timeInDetectedSec": 39582,
        "timeInDetectedLatLng": [
          33481223,
          -86787985
        ],
        "timeOutDetectedSec": 40795,
        "timeOutDetectedLatLng": [
          33481223,
          -86788790
        ]
      }
    }
  ],
  "trackingData": {
    "driversTrackingData": {
      "a08213e6-673f-4efc-955e-2bf587813162": {
        "current": {
          "departure": {
            "sec": 28898,
            "latLng": [
              33817872,
              -87266893
            ]
          },
          "arrival": {
            "sec": 43247,
            "latLng": [
              33817942,
              -87266921
            ]
          }
        },
        "history": [
          {
            "eventType": "departure",
            "action": "upsert",
            "fix": {
              "sec": 28898,
              "latLng": [
                33817872,
                -87266893
              ]
            }
          },
          {
            "eventType": "arrival",
            "action": "upsert",
            "fix": {
              "sec": 43247,
              "latLng": [
                33817942,
                -87266921
              ]
            }
          }
        ]
      },
      "a3935987-4944-462f-b602-4a3a12beeeff": {
        "current": {
          "departure": {
            "sec": 50436,
            "latLng": [
               33817873,
              -87266891
            ]
          },
          "arrival": {
            "sec": 64815,
            "latLng": [
              33817949,
              -87266928
            ]
          }
        },
        "history": [
          {
            "eventType": "departure",
            "action": "upsert",
            "fix": {
              "sec": 50436,
              "latLng": [
                33817873,
                -87266891
              ]
            }
          },
          {
            "eventType": "arrival",
            "action": "upsert",
            "fix": {
              "sec": 64815,
              "latLng": [
                33817949,
                -87266928
              ]
            }
          }
        ]
      }
    }
  }
}
Property Type Description
id String Route ID, formatted as “vehicleId-yyyyMMdd” (e.g.: “0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20170429”)
revision int The Route revision number. Changes every time the Route is updated
date DateString The Route date
vehicleId UUID ID of the Vehicle servicing this Route
driverId UUID OR null Null if no driver has been assigned to this route
vehicleViolations list of enum A list of violated Vehicle constraints. Values are:
  • LD: One or more maximum load allowances have been exceeded
  • NLD: One or more load assume a negative value during the execution
  • TWS: Route starts before the working time window opens
  • TWE: Route ends after the working time window closes
  • DT: Maximum driving time exceeded
  • WT: Maximum working time exceeded
  • ML: Maximum drive distance exceeded
  • OR: Maximum number of serviced Orders exceeded
steps list of RouteStep Ordered list of RouteSteps ( e.g.: departure, delivery #1, delivery #2, …, delivery #n, arrival )
trackingData TrackingDataRegistry Route-related tracking data, ‘null’ if no tracking data is present

RouteStep Object properties

{
  "type": "delivery",
  "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
  "idleTimeSec": 0,
  "perStopTimeSec": 0,
  "arrivalSec": 34200,
  "startSec": 34200,
  "endSec": 36000,
  "driveToNextSec": -1,
  "distanceToNextMt": -1,
  "stopIdx": 0,
  "displayLabel": "1.1",
  "trackingLink": "https://l-nk.io/xZv4ARB",
  "violations": ["TGI", "TW"],
  "trackingData": {
    "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
    "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
    "timeInSec": 34526,
    "timeInLatLng": [
      33817872,
      -87266893
    ],
    "timeOutSec": -1,
    "timeOutLatLng": null,
    "status": "done",
    "statusSec": 35912,
    "statusLatLng": [
      33817872,
      -87266893
    ],
    "statusReason": null,
    "timeInDetectedSec": 34201,
    "timeInDetectedLatLng": [
      33817942,
      -87266921
    ],
    "timeOutDetectedSec": 35935,
    "timeOutDetectedLatLng": [
      33817404,
      -87266657
    ]
  }
}
Property Type Description
type enum One of departure, arrival, pickup, delivery, brk, preparation, closeOut.
Note: RouteSteps referencing “service” Orders (orders flagged with “isService=true”. See also the description of Order.isService) will have type=delivery
orderId String OR null Only set for pickup and delivery types, null otherwise
idleTimeSec int The time spent idling before start servicing an Order. It is equal to startSec – arrivalSec. Only relevant for pickup and delivery types, 0 otherwise
perStopTimeSec int
arrivalSec int The time of arrival in seconds since midnight. -1 for departure types
startSec int Service start time for pickup and delivery types, start-of-break time for brk types, preparation start time for preparation, settle start time for closeOut, identical to arrivalSec for arrival types. -1 for departure types
endSec int Departure time, in seconds since midnight, for pickup, delivery and departure types, end-of-break time for brk types, preparation end time for preparation, settle end time for closeOut, -1 for arrival types
driveToNextSec int Driving time, in seconds, to next stop. -1 when not available
distanceToNextMt int Distance to next stop. -1 when not available
stopIdx int Number of vehicle’s stop the current step belongs to. -1 for brk, ‘preparation’ and ‘closeOut’ types
displayLabel String (only for pickup and delivery types, null otherwise)
trackingLink String (only for pickup and delivery types, and only for Routes returned by the Time Of Arrival APIs, null otherwise) the tracking Link generated for this OrderStep, if any
violations list of enum A list of violated Order constraints. Values are:
  • VE: Forced Vehicle assignment violated
  • TGI: TagsIn constraint violated: the Vehicle does not define all the tags required by the OrderStep
  • TGO: TagsOut constraint violated: the Vehicle defines at least one tag banned by the OrderStep
  • ELG: Order Eligibility constraint violated
  • TW: Time Windows constraint violated
  • RGN: Regions constraint violated: none of the Regions this OrderStep belongs to is associated to the Vehicle serving it
  • PDM: Pickup&Delivery constraint violated: paired OrderStep is missing (unassigned or assigned to other Route)
  • PDI: Pickup&Delivery constraint violated: delivery served before pickup
  • OWB: outside working-time bounds: an orderstep tracking data is outside the right start-end window defined by driver
trackingData TrackingData (only for pickup and delivery types, and only for Routes returned by the Time Of Arrival APIs, null otherwise)

TrackingDataRegistry Object properties

{
  "driversTrackingData": {
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "current": {
        "departure": {
          "sec": 28898,
          "latLng": [
            33817872,
            -87266893
          ]
        },
        "arrival": {
          "sec": 43247,
          "latLng": [
            33817942,
            -87266921
          ]
        }
      },
      "history": [
        {
          "eventType": "departure",
          "action": "upsert",
          "fix": {
            "sec": 28898,
            "latLng": [
              33817872,
              -87266893
            ]
          }
        },
        {
          "eventType": "arrival",
          "action": "upsert",
          "fix": {
            "sec": 43247,
            "latLng": [
              33817942,
              -87266921
            ]
          }
        }
      ]
    },
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "current": {
        "departure": {
          "sec": 50436,
          "latLng": [
            33817873,
            -87266891
          ]
        },
        "arrival": {
          "sec": 64815,
          "latLng": [
            33817949,
            -87266928
          ]
        }
      },
      "history": [
        {
          "eventType": "departure",
          "action": "upsert",
          "fix": {
            "sec": 50436,
            "latLng": [
              33817873,
              -87266891
            ]
          }
        },
        {
          "eventType": "arrival",
          "action": "upsert",
          "fix": {
            "sec": 64815,
            "latLng": [
              33817949,
              -87266928
            ]
          }
        }
      ]
    }
  }
}
Property Type Description
driversTrackingData map[UUID] DriverTrackingData Tracked working time start/end, sent by drivers who executed the route. The map key is the driver ID the value object is related to.

DriverTrackingData Object properties

{
  "current": {
    "departure": {
      "sec": 36512,
      "latLng": [
        33817872,
        -87266893
      ]
    },
    "arrival": {
      "sec": 72368,
      "latLng": [
        33817942,
        -87266921
      ]
    }
  },
  "history": [
    {
      "eventType": "departure",
      "action": "upsert",
      "fix": {
        "sec": 36512,
        "latLng": [
          33817872,
          -87266893
        ]
      }
    },
    {
      "eventType": "arrival",
      "action": "upsert",
      "fix": {
        "sec": 72368,
        "latLng": [
          33817942,
          --87266921
        ]
      }
    }
  ]
}
Property Type Description
current CurrentDriverTrackignData Actual start and end tracking data about driver start and end
history list of HistoricalDriverTrackingData All tracked driver’s starts and ends

CurrentDriverTrackingData Object properties

{
  "departure": {
    "sec": 36512,
    "latLng": [
      33817872,
      -87266893
    ]
  },
  "arrival": {
    "sec": 72368,
    "latLng": [
      33817942,
      -87266921
    ]
  }
}
Property Type Description
departure Fix Execution data of the actual tracked working time start
arrival Fix Execution data of the actual tracked working time end, null if no end is tracked

HistoricalDriverTrackingData Object properties

{
  "eventType": "departure",
  "action": "upsert",
  "fix": {
    "sec": 36512,
    "latLng": [
      33817872,
      -87266893
    ]
  }
}
Property Type Description
eventType enum One of departure, arrival
action enum One of upsert, delete
fix Fix Execution data of the tracked event, null if action is delete

TrackingData Object properties

{
  "driverId": "a08213e6-673f-4efc-955e-2bf587813162",
  "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "timeInSec": 34526,
  "timeInLatLng": [
    33817872,
    -87266893
  ],
  "timeOutSec": -1,
  "timeOutLatLng": null,
  "status": "done",
  "statusSec": 35912,
  "statusLatLng": [
    33817872,
    -87266893
  ],
  "statusReason": null,
  "timeInDetectedSec": 34201,
  "timeInDetectedLatLng": [
    33817942,
    -87266921
  ],
  "timeOutDetectedSec": 35935,
  "timeOutDetectedLatLng": [
    33817404,
    -87266657
  ],
  "trackedLoadMap": {
    "load-name": {
      "latLng": [
        33817872,
        -87266893
      ],
      "timeSec": 3900,
      "value": 1900
    }
  },
  "trackedCustomFieldMap": {
    "customField-name": {
      "latLng": [
        33817872,
        -87266893
      ],
      "timeSec": 4200,
      "value": "ABCD"
    }
  }
}
Property Type Description
driverId UUID OR null Id of the last Driver that updated this tracking data object. null if the last update was manually entered via the Web Application
vehicleId UUID Id of the Vehicle associated to the Driver account that reported this data
timeInSec int Time, in seconds since midnight, when the reported time-in event (service started as reported by the Driver) occurred. -1 if no time-in has been reported
timeInLatLng LatLng OR null Coordinates of the time-in event, where available
timeOutSec int Time, in seconds since midnight, when the reported time-out event (service completed as reported by the Driver) occurred. -1 if no time-out has been reported
timeOutLatLng LatLng OR null Coordinates of the time-out event, where available
status enum OR null One of reschedule, done. null if no status has been reported
statusSec int Time, in seconds since midnight, when the status-reported event occurred.-1 if no status has been reported
statusLatLng LatLng OR null Coordinates of the status-reported event, where available
statusReason String OR null Details about the status of a not completed (status set to reschedule) step, where available
timeInDetectedSec int Time, in seconds since midnight, when the detected time-in event (service started as detected by the Mobile App) occurred. -1 if no time-in could be detected
timeInDetectedLatLng LatLng OR null Coordinates of the detected time-in event. Null if no time-in could be detected
timeOutDetectedSec int Time, in seconds since midnight, when the detected time-out event (service completed as detected by the Mobile App) occurred. -1 if no time-out could be detected
timeOutDetectedLatLng LatLng OR null Coordinates of the time-out event. Null if no time-out could be detected
trackedLoadMap TrackedLoad OR null Map containing all the load tracked via Mobile App.
trackedCustomFieldMap TrackedCustomFields OR null Map containing lal the custom fields tracked via Mobile App.
pods PodContainer OR null Container of categorized Proof Of Delivery objects collected for the RouteStep associated to this TrackingData

Note: in case of tracking data related to preparation and closeOut steps, only the following fields have to been taken into account: driverId, vehicleId, timeInSec, timeInLatLng, timeOutSec, timeOutLatLng

PodContainer Object properties

{
  "signatures": {
    "customer": {
      "sec": 36813,
      "latLng": [33817872, -87266893],
      "text": "John Black",
      "token": "20151204-429defc8-be30b653.png"
    }
  },
  "pictures": {
    "picture-1": {
      "sec": 35427,
      "latLng": null,
      "text": "Minor damage in lower left corner",
      "token": "20151204-429defc8-fa6e00dd.jpg"
    },
    "picture-2": { ... },  //
    ...                    // More pictures
  },
  "note": {
    "sec": 35360,
    "latLng": [33817872, -87266893],
    "text": "Best parking spot is 50mt ahead"
  }
  "barcodes": [
    {
      "sec": 35330,
      "latLng": [33817872, -87266893],
      "barcode": "1234567890",
      "barcodeStatus": "SCANNED"
    }
  ]
}
Property Type Description
signatures map[SignatureType] Pod Signature images. SignatureType can be driver or customer
pictures map[String] Pod Pictures. The map key is the externally provided ID associated to the picture-type Proof of Delivery
note Pod Textual note
barcodes list of BarcodePod List of scanned barcodes

Pod Object properties


// Signature Pod Example
{
  "sec": 36813,
  "latLng": [33817872, -87266893],             // Coordinates. Optional
  "text": "John Black",                        // Textual description. Typically "Name/Surname". Optional
  "token": "20151204-429defc8-be30b653.png"
}

// Picture Pod Example
{
  "sec": 35427,
  "latLng": null,                              // Coordinates. Optional
  "text": "Minor damage in lower left corner", // Textual description. Optional
  "token": "20151204-429defc8-fa6e00dd.jpg"
}

// Audio Pod Example
{
  "sec": 37143,
  "latLng": null,                              // Coordinates. Optional
  "text": "Clanking noise from left engine",   // Textual description. Optional
  "token": "20151204-429defc8-56b1f8b3.aac"
}

// Note Pod Example
{
  "sec": 35360,
  "latLng": [33817872, -87266893],             // Coordinates. Optional
  "text": "Best parking spot is 50mt ahead"
}
Property Type Description
sec int Time, in seconds since midnight, when the Proof of Delivery was either posted or last updated
latLng LatLng OR null Coordinates of the Proof of Delivery event, where available
text String Text attached to the Proof of Delivery item
token String Only provided for image-type or audio-type Proof of Delivery items (signatures, pictures and audio-recordings). Used to download the referenced binary item

BarcodePod Object properties

{
  "sec": 35330,
  "latLng": [33817872, -87266893],
  "barcode": "1234567890",
  "barcodeStatus": "SCANNED"
}
Property Type Description
sec int Time, in seconds since midnight, when the Proof of Delivery was either posted or last updated
latLng LatLng OR null Coordinates of the Proof of Delivery event, where available
barcode String The barcode
barcodeStatus enum One of SCANNED, UNREADABLE, MISSING_BARCODE, MISSING_PACKAGE

ApprovedRoute Object properties

{
  "route": {
    "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
    "revision": 166,
    "date": "20151204",
    "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
    "driverId": "a3935987-4944-462f-b602-4a3a12beeeff",
    "steps": [
      {
        "type": "departure",
        "idleTimeSec": 0,
        "perStopTimeSec": 0,
        "arrivalSec": 0,
        "startSec": 0,
        "endSec": 28800,
        "driveToNextSec": 2918,
        "distanceToNextMt": 73402,
        "stopIdx": 0,
        "displayLabel": ""
      },
      {
        "type": "preparation",
        "idleTimeSec": 0,
        "perStopTimeSec": 0,
        "arrivalSec": 28800,
        "startSec": 28800,
        "endSec": 29400,
        "driveToNextSec": 2318,
        "distanceToNextMt": 73402,
        "stopIdx": -1
      },
      {
        "type": "pickup",
        "orderId": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
        "idleTimeSec": 0,
        "perStopTimeSec": 0,
        "arrivalSec": 31718,
        "startSec": 31718,
        "endSec": 32318,
        "driveToNextSec": 2917,
        "distanceToNextMt": 73549,
        "stopIdx": 1,
        "displayLabel": "2.1"
      },
      {
        "type": "arrival",
        "idleTimeSec": 0,
        "perStopTimeSec": 0,
        "arrivalSec": 35235,
        "startSec": 35235,
        "endSec": 35235,
        "driveToNextSec": 0,
        "distanceToNextMt": 0,
        "stopIdx": 2,
        "displayLabel": ""
      }
    ]
  },
  "vehicle": {
    "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
    "idx": 2,
    "externalId": "Vehicle 2",
    "tracked": true,
    "settings": {
      "20151204": {
        "available": true,
        "notes": "",
        "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "timeWindow": {
          "startSec": 28800,
          "endSec": 61200
        },
        "flexStartTime": true,
        "perStopCost": 0,
        "perStopTimeSec": 0,
        "maxWorkingTimeSec": 0,
        "maxDrivingTimeSec": 0,
        "maxDistanceMt": 0,
        "maxOrders": 0,
        "breaks": [],
        "loadCapacities": {
          "people": 600
        },
        "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
        "activationCost": 0,
        "drivingTimeCost": 2000,
        "idleTimeCost": 2000,
        "serviceTimeCost": 2000,
        "breakTimeCost": 2000,
        "kmCost": 100,
        "tags": [
          "heavy"
        ],
        "speedFactor": 100,
        "minWorkingTimeSec": 0,
        "minLoadCapacities": {},
        "preparationTimeSec": 600,
        "closeOutTimeSec": 0
      }
    }
  },
  "driver": {
    "id": "a3935987-4944-462f-b602-4a3a12beeeff",
    "name": "Driver 1",
    "summarizeFutureMobileRoute": false,
    "mobileFutureDaysVisibility": 2,
    "email": "driver1@example.com"
  },
  "orders": {
    "1066ecd2-8171-4daf-a8f3-9bf302a2a38f": {
      "id": "1066ecd2-8171-4daf-a8f3-9bf302a2a38f",
      "name": "Order 6",
      "eligibility": {
        "type": "any"
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "email": "mail@companyname.com",
        "phone": "+18007620301",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  }
}
Property Type Description
route Route The Route object
vehicle VehicleFull The Vehicle referenced by the Route, including VehicleSettings for the Route’s date
driver Driver OR null The Driver referenced by the Route (if any)
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the Route
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and the Vehicle

RouteSequence Object properties

{
  "routeId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151207",
  "orderSteps": [
    {
      "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
      "type": "delivery"
    },
    {
      "orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
      "type": "pickup"
    }
  ]
}
Property Type Description
routeId String ID of the target Route (must be a new, non-existing Route)
orderSteps list of OrderStepIdentifier List of OrdersSteps to be assigned to the target Route in the given order (must not be already assigned to other existing Routes)

ExecutionEvent objects

ExecutionEvent Object properties

{
  "type": "timeIn",
  "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
  "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "orderStepType": "delivery",
  "date": "20151204",
  "data": {
    "sec": 35132
  }
}

{
  "type": "statusUpdate",
  "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
  "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "orderStepType": "delivery",
  "date": "20151204",
  "data": {
    "sec": 36863,
    "status": "done",
    "statusReason": null
  }
}

{
  "type": "picture",
  "orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
  "vehicleId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6",
  "orderStepType": "delivery",
  "date": "20151112",
  "data": {
    "id": "picture-1",
    "sec": 35427,
    "text": "Minor damage in lower left corner",
    "mime": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYmICAAAQAAei1PI/AAAAAElFTkSuQmCC"
  }
}
Property Type Description
type enum One of timeIn, timeOut, detectedTimeIn, detectedTimeOut, statusUpdate, podSignature, podPicture, podAudio, podBarcodes, podNote, departure, arrival, preparationTimeIn, preparationTimeOut, closeOutTimeIn, closeOutTimeOut, loadTracking, customFieldTracking
orderId UUID Id of the Order. Together with orderStepType identifies the OrderStep this event applies to
orderStepType enum One of pickup or delivery. Together with orderId identifies the OrderStep this event applies to
date DateString Date of the event. Together with vehicleId identifies the Route this event applies to
vehicleId UUID Id of the Vehicle associated with this event. Together with date identifies the Route this event applies to
driverId UUID OR null Id of the Driver associated with this event, if known
Mandatory if type is departure or arrival, optional otherwise
clientTs long Optional: Timestamp of the event in seconds (Unix epoch) as recorded by the device (e.g.: mobile application)
data One of:
EEDataTimeIn
EEDataTimeOut
EEDataDetectedTimeIn
EEDataDetectedTimeOut
EEDataDeparture
EEDataArrival
EEDataStatusUpdate
EEDataTrackingLoad
EEDataTrackingCustomField
EEDataPodSignature
EEDataPodPicture
EEDataPodAudio
EEDataPodBarcodes
EEDataPodNote		 Event data object. Object type varies based on the event type

EEDataTimeIn Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}
Property Type Description
sec int Reported time-in time, in seconds since midnight (e.g.: time-in at 6pm = 64800)
latLng LatLng OR null Optional: reported time-in coordinates.

EEDataTimeOut Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}
Property Type Description
sec int Reported time-out time, in seconds since midnight (e.g.: time-out at 6pm = 64800)
latLng LatLng OR null Optional: reported time-out coordinates

EEDataDetectedTimeIn Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}

Note: Use only if integrating with a custom mobile application implementing its own time-in auto-detection logic.

Property Type Description
sec int Auto-detected time-in time, in seconds since midnight (e.g.: time-in at 6pm = 64800)
latLng LatLng OR null Optional: detected time-in coordinates.

EEDataDetectedTimeOut Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}

Note: Use only if integrating with a custom mobile application implementing its own time-out auto-detection logic.

Property Type Description
sec int Auto-detected time-out time, in seconds since midnight (e.g.: time-out at 6pm = 64800)
latLng LatLng OR null Optional: auto-detected time-out coordinates

EEDataDeparture Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}
Property Type Description
sec int Mandatory: working time start time, in seconds since midnight (e.g.: start at 6pm = 64800)
latLng LatLng Mandatory: working time start coordinates

EEDataArrival Object properties

{
  "sec": 35132,
  "latLng": [33817872, -87266893]
}
Property Type Description
sec int Mandatory: working time end time, in seconds since midnight (e.g.: end at 6pm = 64800)
latLng LatLng Mandatory: working time end coordinates

EEDataStatusUpdate Object properties

{
  "sec": 35132,
  "status": "done",
  "latLng": [33817872, -87266893],
  "statusReason": null
}
Property Type Description
sec int Reported status-update time, in seconds since midnight (e.g.: update at 6pm = 64800)
status enum OR null Flags the Order as either reschedule (to be rescheduled at some later date/time) or done (marked as done).
Sending null as value removes any previous status
latLng LatLng OR null Optional: reported status-update coordinates
statusReason String OR null Details about the status of a not completed (status set to reschedule) step.
Note: if status is not set to reschedule, statusReason will be automatically set to null; moreover, if the statusReason value is not contained into statusReasons list of the Territory object (case-sensitive check) it will be automatically set to null

EEDataTrackingLoad Object properties

{
  "sec": 3900,
  "latLng": [33817872, -87266893],
  "trackedLoads":{
      "load-name": 1900
  }
}
Property Type Description
sec int Time, in seconds since midnight, when the load was updated (from the Mobile App).
latLng LatLng OR null Optional: reported load update coordinates
trackedLoads Map[String, int] Map representing the new value set by the user (via the Mobile App).
Note: the key value of this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23

EEDataTrackingCustomField Object properties

{
  "sec": 4200,
  "latLng": [33817872, -87266893],
  "trackedCustomFields":{
      "custom-field-name": "new-value"
  }
}
Property Type Description
sec int Time, in seconds since midnight, when the custom field was updated (from the Mobile App).
latLng LatLng OR null Optional: reported custom field update coordinates
trackedCustomFields Map[String, String] Map representing the new value set by the user (via the Mobile App).

EEDataPodSignature Object properties

{
  "id": "customer",
  "sec": 36813,
  "text": "John Black",
  "mime": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYmICAAAQAAei1PI/AAAAAElFTkSuQmCC"
}
Property Type Description
id enum One of customer or driver
sec int Reported signature time, in seconds since midnight (e.g.: signature at 6pm = 64800)
latLng LatLng OR null Optional: reported coordinates
text String OR null Optional: textual note attached to the signature image (e.g.: textual name/surname)
mime enum One of “image/png” or “image/jpeg”
data String Base64-encoded binary image data. Binary image format must match the provided mime type.
Set to null to remove the signature-type Proof of Delivery associated to the given id
LIMITS: Maximum base64-encoded size is 2_796_202 characters (2MB).

EEDataPodPicture Object properties

{
  "id": "picture-1",
  "sec": 35427,
  "text": "Minor damage in lower left corner",
  "mime": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYmICAAAQAAei1PI/AAAAAElFTkSuQmCC"
}
Property Type Description
id String Externally provided ID associated to the picture (useful to update or remove the picture at a later time)
sec int Reported picture time, in seconds since midnight (e.g.: picture at 6pm = 64800)
latLng LatLng OR null Optional: reported coordinates
text String OR null Optional: textual note attached to the picture image (e.g.: “package seal is broken”)
mime enum One of “image/png” or “image/jpeg”
data String Base64-encoded binary image data. Binary image format must match the provided mime type.
Set to null to remove the picture-type Proof of Delivery associated to the given id
LIMITS: Maximum base64-encoded size is 2_796_202 characters (2MB).

EEDataPodAudio Object properties

{
  "id": "audio-1",
  "sec": 37143,
  "text": "Example of clanking noise coming from left engine",
  "mime": "audio/aac",
  "data": "//FsQBUf/N4CAExhdmM1Ny42NS4xMDAAAdRlD8zvnW+a3jOON8SvPvdby...[truncated]"
}
Property Type Description
id String Externally provided ID associated to the audio recording (useful to update or remove the audio at a later time)
sec int Reported time when the audio was recorded, in seconds since midnight (e.g.: audio recorded at 6pm = 64800)
latLng LatLng OR null Optional: reported coordinates
text String OR null Optional: textual note attached to the audio recording (e.g.: “example of clanking noise coming from left engine”)
mime enum One of “audio/mpeg” or “audio/aac”
data String Base64-encoded binary audio data. Binary audio format must match the provided mime type.
Set to null to remove the audio-type Proof of Delivery associated to the given id
LIMITS: Maximum base64-encoded size is 2_796_202 characters (2MB).

EEDataPodBarcodes Object properties

{
  "barcodes": [
    {"barcode": "1234", "barcodeStatus": "SCANNED", "sec": 8200},
    {"barcode": "5678", "barcodeStatus": "UNREADABLE", "sec": 8232}
  ]
}
Property Type Description
barcodes list of EEPodBarcode The list replaces all the barcodes proofs of delivery for the Order Step

EEPodBarcodes Object properties

{
  "sec": 8200,
  "barcode": "1234",
  "barcodeStatus": "SCANNED"
}
Property Type Description
sec int Reported time when the audio was recorded, in seconds since midnight (e.g.: audio recorded at 6pm = 64800)
latLng LatLng OR null Optional: reported coordinates
barcode String The barcode
LIMITS: Can be at maximum 100 characters long and cannot contain commas.
barcodeStatus enum One of SCANNED, UNREADABLE, MISSING_BARCODE, MISSING_PACKAGE

EEDataPodNote Object properties

{
  "sec": 35203,
  "text": "Best parking spot is 50mt ahead"
}
Property Type Description
sec int Reported note time, in seconds since midnight (e.g.: note at 6pm = 64800)
latLng LatLng OR null Optional: reported coordinates
text String Note text. Set to null to remove the note-type Proof of Delivery

Customer Notifications objects

OrderStepNotification Object properties

{
  "orderStepId": {
    "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "type": "delivery"
  },
  "kind": "SMS",
  "sentTs": 1610115318405,
  "status": "SENT",
  "subject": null,
  "recipient": "+11111111111",
  "bodyPlainText": "Your order #123456 from Company XYZ will be delivered today",
  "bodyHtml": null,
  "errorCode": null,
  "errorName": null
}
Property Type Description
orderStepId OrderStepIdentifier The id of the OrderStep for which this notification was sent
kind enum One of SMS or EMAIL
sentTs long Epoch millisecond timestamp of when the notification was created
recipient String Recipient of the notification. It’s a phone number when kind is SMS and an email address when kind is EMAIL.
status enum One of PENDING or SENT or FAILED.
bodyPlainText String The message of the notification. When kind is EMAIL contains the plain text of the email with BR tags converted to newlines.
bodyHtml String Present only when kind is EMAIL. Contains the html body of the message
subject String Email subject when kind is EMAIL. Null otherwise
errorCode int Optional, might contain additional error information when status is FAILED
errorName string Optional, textual description for errorCode

Proposals objects

TimeSlot Object properties

{
  "pickupTimeWindows": [
    {
      "startSec": 45000,
      "endSec": 46800
    }
  ],
  "deliveryTimeWindows": [
    {
      "startSec": 46800,
      "endSec": 50400
    }
  ],
  "date": "20151204"
}
Property Type Description
pickupTimeWindows list of TimeWindow The list of TimeWindows for this slot for the pickup OrderStep. Mandatory if the Proposal’s order defines a pickup OrderStep, null otherwise.
LIMITS: cannot contain more than 4 TimeWindows
deliveryTimeWindows list of TimeWindow The list of TimeWindows for this slot for the delivery OrderStep. Mandatory if the Proposal’s order defines a delivery OrderStep, null otherwise.
LIMITS: cannot contain more than 4 TimeWindows
date DateString The eligible date for this slot.
LIMITS: must not be a past date

ProposalsSet Object properties

{
  "requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
  "requestStatus": "COMPLETED",
  "expiryTs": 1423047900,
  "order": {
    "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "name": "Order coming from Proposals API",
    "eligibility": {
      "type": "any"
    },
    "forceVehicleId": null,
    "priority": 0,
    "loads": {
      "pounds": 400
    },
    "delivery": {
      "location": {
        "address": "2001 2nd Ave, Jasper, AL 35501, USA"
      },
      "timeWindows": [],
      "notes": "Order for which we want to compute a set of proposals",
      "email": "mail@companyname.com",
      "phone": "+18007620301",
      "serviceTimeSec": 1800,
      "tagsIn": [],
      "tagsOut": [],
      "customFields": {
        "my custom field": "custom field content",
        "orderId": "abcd1234"
      }
    },
    "isService": false
  },
  "proposals": [
    {
      "status": "NOT_FOUND"
    },
    {
      "status": "FOUND",
      "data": {
        "routes": {
          "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
            "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
            "revision": -1,
            "date": "20151204",
            "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "driverId": null,
            "steps": [
              {
                "type": "departure",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 0,
                "startSec": 0,
                "endSec": 28800,
                "driveToNextSec": 0,
                "distanceToNextMt": 0,
                "stopIdx": 0,
                "displayLabel": ""
              },
              {
                "type": "preparation",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 28800,
                "startSec": 28800,
                "endSec": 29400,
                "driveToNextSec": 2318,
                "distanceToNextMt": 73402,
                "stopIdx": -1
              },
              {
                "type": "pickup",
                "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 31718,
                "startSec": 31718,
                "endSec": 32318,
                "driveToNextSec": 2917,
                "distanceToNextMt": 73549,
                "stopIdx": 1,
                "displayLabel": ""
              },
              {
                "type": "delivery",
                "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 35235,
                "startSec": 35235,
                "endSec": 36135,
                "driveToNextSec": 48,
                "distanceToNextMt": 334,
                "stopIdx": 2,
                "displayLabel": ""
              },
              {
                "type": "delivery",
                "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 38265,
                "startSec": 38265,
                "endSec": 40065,
                "driveToNextSec": 123,
                "distanceToNextMt": 846,
                "stopIdx": 3,
                "displayLabel": ""
              },
              {
                "type": "arrival",
                "idleTimeSec": 0,
                "perStopTimeSec": 0,
                "arrivalSec": 40188,
                "startSec": 40188,
                "endSec": 40188,
                "driveToNextSec": 0,
                "distanceToNextMt": 0,
                "stopIdx": 4,
                "displayLabel": ""
              }
            ]
          }
        },
        "orders": {
          "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
            "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
            "name": "Order coming from Proposals API",
            "eligibility": {
              "on": "20151204"
           },
            "forceVehicleId": null,
            "priority": 0,
            "loads": {
              "pounds": 400
            },
            "delivery": {
              "location": {
                "address": "2001 2nd Ave, Jasper, AL 35501, USA"
              },
              "timeWindows": [
                {
                  "startSec": 46800,
                  "endSec": 50400
                }
              ],
              "notes": "Order for which we want to compute a set of proposals",
              "email": "mail@companyname.com",
              "phone": "+18007620301",
              "serviceTimeSec": 1800,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {
                "my custom field": "custom field content",
                "orderId": "abcd1234"
              }
            },
            "isService": false
          },
          "e2524914-3611-433b-9209-3ee59ee3996e": {
            "id": "e2524914-3611-433b-9209-3ee59ee3996e",
            "name": "Order 6",
            "eligibility": {
              "type": "any",
              "onDates": [
                "20151203"
              ]
            },
            "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "priority": 0,
            "loads": {
              "people": 400
            },
            "pickup": {
              "depotId": null,
              "location": {
                "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
                "latLng": [
                  33480873,
                  -86788220
                ],
                "status": "OK"
              },
              "timeWindows": [],
              "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
              "email": "mail@companyname.com",
              "phone": "+18007620301",
              "serviceTimeSec": 600,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {}
            },
            "delivery": null,
            "isService": false
          },
          "deb5a845-40f8-42e0-963e-9646531894a4": {
            "id": "deb5a845-40f8-42e0-963e-9646531894a4",
            "name": "order2",
            "eligibility": {
              "type": "on",
              "onDates": [
                "20151205"
              ]
            },
            "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "priority": 0,
            "loads": {},
            "pickup": null,
            "delivery": {
              "depotId": null,
              "location": {
                "address": "33.833605,-87.277556",
                "latLng": [
                  33833604,
                  -87277556
                ],
                "status": "OK"
              },
              "timeWindows": [],
              "notes": "",
              "email": "mail@companyname.com",
              "phone": "+18007620301",
              "serviceTimeSec": 900,
              "tagsIn": [],
              "tagsOut": [],
              "customFields": {}
            },
            "isService": false
          }
        },
        "vehicles": {
          "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
            "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
            "idx": 2,
            "externalId": "Vehicle 2",
            "tracked": true,
            "color": "5500FF",
            "settings": {
              "20151203": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {},
                "preparationTimeSec": 600,
                "closeOutTimeSec": 0
              },
              "20151204": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {},
                "preparationTimeSec": 600,
                "closeOutTimeSec": 0
              },
              "20151205": {
                "available": true,
                "notes": "",
                "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
                "timeWindow": {
                  "startSec": 28800,
                  "endSec": 61200
                },
                "flexStartTime": true,
                "perStopCost": 0,
                "perStopTimeSec": 0,
                "maxWorkingTimeSec": 0,
                "maxDrivingTimeSec": 0,
                "maxDistanceMt": 0,
                "maxOrders": 0,
                "breaks": [],
                "loadCapacities": {
                  "people": 600
                },
                "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
                "activationCost": 0,
                "drivingTimeCost": 2000,
                "idleTimeCost": 2000,
                "serviceTimeCost": 2000,
                "breakTimeCost": 2000,
                "kmCost": 100,
                "tags": [
                  "heavy"
                ],
                "speedFactor": 100,
                "minWorkingTimeSec": 0,
                "minLoadCapacities": {},
                "preparationTimeSec": 600,
                "closeOutTimeSec": 0
              }
            }
          }
        },
        "depots": {
          "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
            "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "name": "TEST",
            "setupCost": -1,
            "setupTimeSec": -1,
            "location": {
              "address": "320 20th St W, Jasper, AL 35501, USA",
              "latLng": [
                33831316,
                -87278355
              ],
              "status": "OK"
            },
            "color": "998800"
          }
        },
        "drivers": {
          "a3935987-4944-462f-b602-4a3a12beeeff": {
            "id": "a3935987-4944-462f-b602-4a3a12beeeff",
            "name": "Driver 1",
            "summarizeFutureMobileRoute": false,
            "mobileFutureDaysVisibility": 2,
            "email": "driver1@example.com"
          }
        }
      },
      "routeCost": 201675,
      "deltaCost": 10498
    },
    {
      "status": "NOT_FOUND"
    }
  ]
}
Property Type Description
requestId String ID associated to the request that generated this set; also doubles as the ID of the set.
requestStatus enum One of PENDING or COMPLETED
expiryTs long Expiry timestamp in seconds (Unix epoch).
The time this set of proposals expires if no proposal is applied
order Order Order associated with this result, the one we’ve computed proposals for.
Note: actual values for the Order’s eligibility and OrderSteps’ timeWindows are finalized based on the applied proposal
proposals list of Proposal For each time slot in the Compute ProposalsSet request, describes the best Route assigment found (if any).
Note: the size of this array matches the size of the timeSlots array in the Compute ProposalsSet request

Proposal Object properties

{
  "status": "FOUND",
  "data": {
    "routes": {
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
        "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
        "revision": -1,
        "date": "20151204",
        "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "driverId": null,
        "steps": [
          {
            "type": "departure",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 0,
            "startSec": 0,
            "endSec": 28800,
            "driveToNextSec": 0,
            "distanceToNextMt": 0,
            "stopIdx": 0,
            "displayLabel": ""
          },
          {
            "type": "preparation",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 28800,
            "startSec": 28800,
            "endSec": 29400,
            "driveToNextSec": 2318,
            "distanceToNextMt": 73402,
            "stopIdx": -1
          },
          {
            "type": "pickup",
            "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 31718,
            "startSec": 31718,
            "endSec": 32318,
            "driveToNextSec": 2917,
            "distanceToNextMt": 73549,
            "stopIdx": 1,
            "displayLabel": ""
          },
          {
            "type": "delivery",
            "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 35235,
            "startSec": 35235,
            "endSec": 36135,
            "driveToNextSec": 48,
            "distanceToNextMt": 334,
            "stopIdx": 2,
            "displayLabel": ""
          },
          {
            "type": "delivery",
            "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 38265,
            "startSec": 38265,
            "endSec": 40065,
            "driveToNextSec": 123,
            "distanceToNextMt": 846,
            "stopIdx": 3,
            "displayLabel": ""
          },
          {
            "type": "arrival",
            "idleTimeSec": 0,
            "perStopTimeSec": 0,
            "arrivalSec": 40188,
            "startSec": 40188,
            "endSec": 40188,
            "driveToNextSec": 0,
            "distanceToNextMt": 0,
            "stopIdx": 4,
            "displayLabel": ""
          }
        ]
      }
    },
    "orders": {
      "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
        "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
        "name": "Order 6 - Proposal",
        "eligibility": {
          "on": "20151204"
       },
        "forceVehicleId": null,
        "priority": 0,
        "loads": {
          "people": 2
        },
        "delivery": {
          "location": {
            "address": "2001 2nd Ave, Jasper, AL 35501, USA"
          },
          "timeWindows": [
            {
              "startSec": 46800,
              "endSec": 50400
            }
          ],
          "notes": "Proposal order to be added via API",
          "email": "mail@companyname.com",
          "phone": "+18007620301",
          "serviceTimeSec": 1800,
          "tagsIn": [],
          "tagsOut": [],
          "customFields": {
            "my custom field": "custom field content",
            "orderId": "abcd1234"
          }
        },
        "isService": false
      },
      "e2524914-3611-433b-9209-3ee59ee3996e": {
        "id": "e2524914-3611-433b-9209-3ee59ee3996e",
        "name": "Order 6",
        "eligibility": {
          "type": "any",
          "onDates": [
            "20151203"
          ]
        },
        "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "priority": 0,
        "loads": {
          "people": 400
        },
        "pickup": {
          "depotId": null,
          "location": {
            "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
            "latLng": [
              33480873,
              -86788220
            ],
            "status": "OK"
          },
          "timeWindows": [],
          "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
          "email": "mail@companyname.com",
          "phone": "+18007620301",
          "serviceTimeSec": 600,
          "tagsIn": [],
          "tagsOut": [],
          "customFields": {}
        },
        "delivery": null,
        "isService": false
      },
      "deb5a845-40f8-42e0-963e-9646531894a4": {
        "id": "deb5a845-40f8-42e0-963e-9646531894a4",
        "name": "order2",
        "eligibility": {
          "type": "on",
          "onDates": [
            "20151205"
          ]
        },
        "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "priority": 0,
        "loads": {},
        "pickup": null,
        "delivery": {
          "depotId": null,
          "location": {
            "address": "33.833605,-87.277556",
            "latLng": [
              33833604,
              -87277556
            ],
            "status": "OK"
          },
          "timeWindows": [],
          "notes": "",
          "email": "mail@companyname.com",
          "phone": "+18007620301",
          "serviceTimeSec": 900,
          "tagsIn": [],
          "tagsOut": [],
          "customFields": {}
        },
        "isService": false
      }
    },
    "vehicles": {
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
        "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
        "idx": 2,
        "externalId": "Vehicle 2",
        "tracked": true,
        "color": "5500FF",
        "settings": {
          "20151203": {
            "available": true,
            "notes": "",
            "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "timeWindow": {
              "startSec": 28800,
              "endSec": 61200
            },
            "flexStartTime": true,
            "perStopCost": 0,
            "perStopTimeSec": 0,
            "maxWorkingTimeSec": 0,
            "maxDrivingTimeSec": 0,
            "maxDistanceMt": 0,
            "maxOrders": 0,
            "breaks": [],
            "loadCapacities": {
              "people": 600
            },
            "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
            "activationCost": 0,
            "drivingTimeCost": 2000,
            "idleTimeCost": 2000,
            "serviceTimeCost": 2000,
            "breakTimeCost": 2000,
            "kmCost": 100,
            "tags": [
              "heavy"
            ],
            "speedFactor": 100,
            "minWorkingTimeSec": 0,
            "minLoadCapacities": {},
            "preparationTimeSec": 600,
            "closeOutTimeSec": 0
          },
          "20151204": {
            "available": true,
            "notes": "",
            "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "timeWindow": {
              "startSec": 28800,
              "endSec": 61200
            },
            "flexStartTime": true,
            "perStopCost": 0,
            "perStopTimeSec": 0,
            "maxWorkingTimeSec": 0,
            "maxDrivingTimeSec": 0,
            "maxDistanceMt": 0,
            "maxOrders": 0,
            "breaks": [],
            "loadCapacities": {
              "people": 600
            },
            "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
            "activationCost": 0,
            "drivingTimeCost": 2000,
            "idleTimeCost": 2000,
            "serviceTimeCost": 2000,
            "breakTimeCost": 2000,
            "kmCost": 100,
            "tags": [
              "heavy"
            ],
            "speedFactor": 100,
            "minWorkingTimeSec": 0,
            "minLoadCapacities": {},
            "preparationTimeSec": 600,
            "closeOutTimeSec": 0
          },
          "20151205": {
            "available": true,
            "notes": "",
            "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
            "timeWindow": {
              "startSec": 28800,
              "endSec": 61200
            },
            "flexStartTime": true,
            "perStopCost": 0,
            "perStopTimeSec": 0,
            "maxWorkingTimeSec": 0,
            "maxDrivingTimeSec": 0,
            "maxDistanceMt": 0,
            "maxOrders": 0,
            "breaks": [],
            "loadCapacities": {
              "people": 600
            },
            "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
            "activationCost": 0,
            "drivingTimeCost": 2000,
            "idleTimeCost": 2000,
            "serviceTimeCost": 2000,
            "breakTimeCost": 2000,
            "kmCost": 100,
            "tags": [
              "heavy"
            ],
            "speedFactor": 100,
            "minWorkingTimeSec": 0,
            "minLoadCapacities": {},
            "preparationTimeSec": 600,
            "closeOutTimeSec": 0
          }
        }
      }
    },
    "depots": {
      "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
        "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
        "name": "TEST",
        "setupCost": -1,
        "setupTimeSec": -1,
        "location": {
          "address": "320 20th St W, Jasper, AL 35501, USA",
          "latLng": [
            33831316,
            -87278355
          ],
          "status": "OK"
        },
        "color": "998800"
      }
    },
    "drivers": {
      "a3935987-4944-462f-b602-4a3a12beeeff": {
        "id": "a3935987-4944-462f-b602-4a3a12beeeff",
        "name": "Driver 1",
        "summarizeFutureMobileRoute": false,
        "mobileFutureDaysVisibility": 2,
        "email": "driver1@example.com"
      }
    }
  },
  "routeCost": 201675,
  "deltaCost": 10498
}
Property Type Description
status enum One of FOUND, NOT_FOUND.
NOT_FOUND indicates that the Order could not be assigned to any Route in the given time slot
data RouteData Contains the single proposed best Route with all related data, or null if status is NOT_FOUND
routeCost int Monetary cost of the route reported within data field, or null if status is NOT_FOUND
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
deltaCost int Monetary cost difference between the route reported within data field and the original route without the Order subject of proposals, or null if status is NOT_FOUND
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23

RouteData Object properties

{
  "routes": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "revision": -1,
      "date": "20151204",
      "vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "driverId": null,
      "steps": [
        {
          "type": "departure",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 0,
          "startSec": 0,
          "endSec": 28800,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 0,
          "displayLabel": ""
        },
        {
          "type": "preparation",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 28800,
          "startSec": 28800,
          "endSec": 29400,
          "driveToNextSec": 2318,
          "distanceToNextMt": 73402,
          "stopIdx": -1
        },
        {
          "type": "pickup",
          "orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 31718,
          "startSec": 31718,
          "endSec": 32318,
          "driveToNextSec": 2917,
          "distanceToNextMt": 73549,
          "stopIdx": 1,
          "displayLabel": ""
        },
        {
          "type": "delivery",
          "orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 35235,
          "startSec": 35235,
          "endSec": 36135,
          "driveToNextSec": 48,
          "distanceToNextMt": 334,
          "stopIdx": 2,
          "displayLabel": ""
        },
        {
          "type": "delivery",
          "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 38265,
          "startSec": 38265,
          "endSec": 40065,
          "driveToNextSec": 123,
          "distanceToNextMt": 846,
          "stopIdx": 3,
          "displayLabel": ""
        },
        {
          "type": "arrival",
          "idleTimeSec": 0,
          "perStopTimeSec": 0,
          "arrivalSec": 40188,
          "startSec": 40188,
          "endSec": 40188,
          "driveToNextSec": 0,
          "distanceToNextMt": 0,
          "stopIdx": 4,
          "displayLabel": ""
        }
      ]
    }
  },
  "orders": {
    "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "name": "Order 6 - Proposal",
      "eligibility": {
        "on": "20151204"
     },
      "forceVehicleId": null,
      "priority": 0,
      "loads": {
        "people": 2
      },
      "delivery": {
        "location": {
          "address": "2001 2nd Ave, Jasper, AL 35501, USA"
        },
        "timeWindows": [
          {
            "startSec": 46800,
            "endSec": 50400
          }
        ],
        "notes": "Proposal order to be added via API",
        "email": "mail@companyname.com",
        "phone": "+18007620301",
        "serviceTimeSec": 1800,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {
          "my custom field": "custom field content",
          "orderId": "abcd1234"
        }
      },
      "isService": false
    },
    "e2524914-3611-433b-9209-3ee59ee3996e": {
      "id": "e2524914-3611-433b-9209-3ee59ee3996e",
      "name": "Order 6",
      "eligibility": {
        "type": "any",
        "onDates": [
          "20151203"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {
        "people": 400
      },
      "pickup": {
        "depotId": null,
        "location": {
          "address": "1919 28th Ave S, Birmingham, AL 35209, United States",
          "latLng": [
            33480873,
            -86788220
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
        "email": "mail@companyname.com",
        "phone": "+18007620301",
        "serviceTimeSec": 600,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "delivery": null,
      "isService": false
    },
    "deb5a845-40f8-42e0-963e-9646531894a4": {
      "id": "deb5a845-40f8-42e0-963e-9646531894a4",
      "name": "order2",
      "eligibility": {
        "type": "on",
        "onDates": [
          "20151205"
        ]
      },
      "forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "priority": 0,
      "loads": {},
      "pickup": null,
      "delivery": {
        "depotId": null,
        "location": {
          "address": "33.833605,-87.277556",
          "latLng": [
            33833604,
            -87277556
          ],
          "status": "OK"
        },
        "timeWindows": [],
        "notes": "",
        "email": "mail@companyname.com",
        "phone": "+18007620301",
        "serviceTimeSec": 900,
        "tagsIn": [],
        "tagsOut": [],
        "customFields": {}
      },
      "isService": false
    }
  },
  "vehicles": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
      "idx": 2,
      "externalId": "Vehicle 2",
      "tracked": true,
      "color": "5500FF",
      "settings": {
        "20151203": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 600,
          "closeOutTimeSec": 0
        },
        "20151204": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 600,
          "closeOutTimeSec": 0
        },
        "20151205": {
          "available": true,
          "notes": "",
          "departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
          "timeWindow": {
            "startSec": 28800,
            "endSec": 61200
          },
          "flexStartTime": true,
          "perStopCost": 0,
          "perStopTimeSec": 0,
          "maxWorkingTimeSec": 0,
          "maxDrivingTimeSec": 0,
          "maxDistanceMt": 0,
          "maxOrders": 0,
          "breaks": [],
          "loadCapacities": {
            "people": 600
          },
          "regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
          "activationCost": 0,
          "drivingTimeCost": 2000,
          "idleTimeCost": 2000,
          "serviceTimeCost": 2000,
          "breakTimeCost": 2000,
          "kmCost": 100,
          "tags": [
            "heavy"
          ],
          "speedFactor": 100,
          "minWorkingTimeSec": 0,
          "minLoadCapacities": {},
          "preparationTimeSec": 600,
          "closeOutTimeSec": 0
        }
      }
    }
  },
  "depots": {
    "08f2f204-caf6-4b98-8767-9fd4e3b46307": {
      "id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
      "name": "TEST",
      "setupCost": -1,
      "setupTimeSec": -1,
      "location": {
        "address": "320 20th St W, Jasper, AL 35501, USA",
        "latLng": [
          33831316,
          -87278355
        ],
        "status": "OK"
      },
      "color": "998800"
    }
  },
  "drivers": {
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "summarizeFutureMobileRoute": false,
      "mobileFutureDaysVisibility": 2,
      "email": "driver1@example.com"
    }
  }
}
Property Type Description
routes map[String] Route A map where the key is the routeId and the value is the associated Route object.
drivers map[String] Driver A map where the key is the driverId and the value is the associated Driver object. Includes Drivers referenced by the listed Routes (if any)
vehicles map[String] VehicleFull A map where the key is the vehicleId and the value is the associated Vehicle object. Includes Vehicles referenced by the listed Routes
orders map[String] Order A map where the key is the orderId and the value is the associated Order object. Includes Orders referenced by the listed Routes. It includes the Proposal Order.
depots map[String] Depot A map where the key is the depotId and the value is the associated Depot object. Includes Depots referenced by the listed Orders and Vehicles

GPS objects

GpsDevice Object properties

{
  "id": "40519",
  "label": "Green Van - SBA 1234A",
  "category": "PHYSICAL",
  "providerName": "WWGPS",
  "active": true
}
Property Type Description
id String GPS Device ID, as provisioned in WorkWave GPS or as defined by the third party provider.
label String Label associated to the GPS Device, as provisioned in WorkWave GPS or as defined in the third party provider account.
category enum One of PHYSICAL or MOBILE.
PHYSICAL indicates vehicle-installed GPS units
MOBILE indicates smartphone units where the WorkWave RouteManager App is installed
providerName String Name of the Connection to the 3rd party provider that provide the device.
WWGPS if using WWGPS tracking Provider.
active boolean Indicates the status of the device. For WWGPS will always be true

GpsSample Object properties

{
  "id": "40519",
  "ts": 1449150077,
  "latLng": [
    33817872,
    -87266893
  ],
  "heading": 60,
  "speedMs": 7,
  "providerName": "WWGPS",
  "active": true
}
Property Type Description
id String GPS Device ID associated to this sample
ts long Sample timestamp, in seconds (Unix epoch)
latLng LatLng Location coordinates of the device at the time the data was sampled
heading int Heading of the device at the time the data was sampled, in degrees. 0 represents north, 90 represents east and so forth. If negative, the value is not provided by the source.
providerName String Name of the Connection to the 3rd party provider that provide the device.
WWGPS if using WWGPS tracking Provider.
active boolean Indicates the status of the device. For WWGPS will always be true

WebHook objects

WebHookSubscriptionInput Object Properties

{
  "url": "https://my.server.com/new-webhook",
  "events":[
      "ORDER_ADDED",
      "ORDER_UPDATED",
      "ORDER_DELETED",
      "ORDER_STEP_DISPATCH_UPDATED"
  ],
  "territoryIds":[
      "0c8bcd10-225a-4acd-a47f-12d1e3077891",
      "ddcbe348-5b4d-483d-9d6c-1b149120ca7e",
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
  ],
  "enabled": true,
  "queueBy": "SUBSCRIPTION",
  "headers": {
    "testHeader": "testHeaderBody",
    "header2" : "header2Body"
  },
  "hmacSecret":"abcd1234"
}

HMAC computation pseudocode. See also examples in other languages

var message = "https://my.server.com/new-webhook?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93";
var secret = "g394g732vhsdfiv34";
var hash = CryptoJS.HmacSHA256(message, secret);
var signature = hash.toString(CryptoJS.enc.Base64); // ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa+U=

HMAC verification pseudocode

var inboundRequestUrl = "https://my.server.com/new-webhook?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93&signature=ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa%2BU%3D"
var signatureFromUrl = new URL(inboundRequestUrl).getQueryStringParameter("signature");
// strip the "signature" parameter from the URL without otherwise altering either the content or the sequence of the other URL parameters
var inboundRequestUrlWithoutSignature = "https://my.server.com/new-callback?reqID=test&nonce=8cf95201-4d3c-4397-9117-d7ee6ad89d93";
var secret = "g394g732vhsdfiv34";
var hash = CryptoJS.HmacSHA256(inboundRequestUrlWithoutSignature, secret);
var computedSignature = hash.toString(CryptoJS.enc.Base64);
var isUrlOk = computedSignature == signatureFromUrl;
Property Type Description
url String The WebHook URL
url String The WebHook URL
events list of enum Optional, defaults to all the events. A list of events that the user wants to subscribe to. Possible values are:
  • ORDER_ADDED: an Order was added
  • ORDER_UPDATED: an Order was updated
  • ORDER_DELETED: an Order was deleted
  • ORDER_STEP_DONE: an OrderStep was completed
  • ORDER_STEP_RESCHEDULED: an Order Step reschedule
  • ORDER_STEP_DISPATCH_UPDATED: an OrderStep from a dispatched Route is updated
  • ORDER_STEP_REVOKED: an OrderStep was removed from a dispatched Route
  • ORDER_STEP_ASSIGNMENT_UPDATED: an assignment for an OrderStep was modified
  • ORDER_STEP_UNASSIGNED: an OrderStep was unassigned
  • ORDER_STEP_TRACKING_DATA_UPDATE: [DEPRECATED] the Tracking Data for one of the OrderSteps was updated
  • ORDER_STEP_TRACKING_DATA_UPDATED: the Tracking Data for one of the OrderSteps was updated
  • DEPOT_ADDED: a Depot was added
  • DEPOT_UPDATED: a Depot was updated
  • DEPOT_DELETED: a Depot was deleted
  • DRIVER_ADDED: a Driver was added
  • DRIVER_UPDATED: a Driver was updated
  • DRIVER_DELETED: a Driver was deleted
  • REGION_ADDED: a Region was added
  • REGION_UPDATED: a Region was updated
  • REGION_DELETED: a Region was deleted
territoryIds list of String Optional, defaults to all the Territories of the Account. List of Terriory ids that the user wants to subscribe to.
hmacSecret String Optional, defaults to null. If set, both a nonce and a signature parameter are added to the querystring of each POSTed webhook. signature is set to the base64 hash computed using HMAC-SHA256 where message is the full URL w/ querystring and secret is hmacSecret. See also the pseudocode in the right panel. This allows the request to be authenticated and to confirm that it is coming from WorkWave RouteManager servers.
headers map[String]String Optional, defaults to null. If set the headers are added to each POSTed webhook. The concatenated string of all the keys and all the values cannot be longer than 256k characters.
enabled boolean Optional, defaults to true. If set to false the subscription will be created but will not send any message to the receiving URL.
queueBy enum Optional, defaults to SUBSCRIPTION. Possible value are:
  • SUBSCRIPTION: ensure the order of notifications at Subscription level. This means that one subscription can not block another subscription working on the same event and territory.
  • TERRITORY: ensure the order of notifications at Territory level. This means that multiple subscriptions for the same event and territory will be executed in order (until the first one get a good response or is discarded it will block the others).
NOTE: the TERRITORY value is mandatory for subcriptions used in Zapier integrations.

WebHookSubscription Object Properties

{
  "id" : "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
  "url": "https://my.server.com/new-webhook",
  "events":[
      "ORDER_ADDED",
      "ORDER_UPDATED",
      "ORDER_DELETED",
      "ORDER_STEP_DISPATCH_UPDATED"
  ],
  "territoryIds":[
      "0c8bcd10-225a-4acd-a47f-12d1e3077891",
      "ddcbe348-5b4d-483d-9d6c-1b149120ca7e",
      "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
  ],
  "enabled": true,
  "queueBy": "SUBSCRIPTION",
  "headers": {
    "testHeader": "testHeaderBody",
    "header2" : "header2Body"
  },
  "hmacSecret":"abcd1234",
  "createTs": "2022-02-17T09:29:27.6167653Z"
}
Property Type Description
id UUID Unique (per-territory) WebHook Subscription ID
url String The WebHook URL
events list of enum Optional, defaults to all the events. A list of events that the user wants to subscribe to. Possible values are:
  • ORDER_ADDED: an Order was added
  • ORDER_UPDATED: an Order was updated
  • ORDER_DELETED: an Order was deleted
  • ORDER_STEP_DONE: an OrderStep was completed
  • ORDER_STEP_RESCHEDULED: an Order Step reschedule
  • ORDER_STEP_DISPATCH_UPDATED: an OrderStep from a dispatched Route is updated
  • ORDER_STEP_REVOKED: an OrderStep was removed from a dispatched Route
  • ORDER_STEP_ASSIGNMENT_UPDATED: an assignment for an OrderStep was modified
  • ORDER_STEP_UNASSIGNED: an OrderStep was unassigned
  • ORDER_STEP_TRACKING_DATA_UPDATE: [DEPRECATED] the Tracking Data for one of the OrderSteps was updated
  • ORDER_STEP_TRACKING_DATA_UPDATED: the Tracking Data for one of the OrderSteps was updated
  • DEPOT_ADDED: a Depot was added
  • DEPOT_UPDATED: a Depot was updated
  • DEPOT_DELETED: a Depot was deleted
  • DRIVER_ADDED: a Driver was added
  • DRIVER_UPDATED: a Driver was updated
  • DRIVER_DELETED: a Driver was deleted
  • REGION_ADDED: a Region was added
  • REGION_UPDATED: a Region was updated
  • REGION_DELETED: a Region was deleted
territoryIds list of String Optional, defaults to all the Territories of the Account. List of Terriory ids that the user wants to subscribe to.
hmacSecret String Optional, defaults to null. If set, both a nonce and a signature parameter are added to the querystring of each POSTed webhook. signature is set to the base64 hash computed using HMAC-SHA256 where message is the full URL w/ querystring and secret is hmacSecret. See also the pseudocode in the right panel. This allows the request to be authenticated and to confirm that it is coming from WorkWave RouteManager servers. (See the related pseudocode in the WebHookSubscriptionInput section for more informations)
headers map[String]String Optional, defaults to null. If set the headers are added to each POSTed webhook. The concatenated string of all the keys and all the values cannot be longer than 256k characters.
enabled boolean Optional, defaults to true. If set to false the subscription will be created but will not send any message to the receiving URL.
queueBy enum Optional, defaults to SUBSCRIPTION. Possible value are:
  • SUBSCRIPTION: ensure the order of notifications at Subscription level. This means that one subscription can not block another subscription working on the same event and territory.
  • TERRITORY: ensure the order of notifications at Territory level. This means that multiple subscriptions for the same event and territory will be executed in order (until the first one get a good response or is discarded it will block the others).
NOTE: the TERRITORY value is mandatory for subcriptions used in Zapier integrations.
createTs String Timestamp for the creation of the object with timezone.

OrderStepAssignment Object Properties

  {
    "orderStepId": {
      "orderId": "0db3c44e-cfa1-4cd5-853d-57749cc3632e",
      "type": "pickup"
    },
    "vehicleId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0",
    "driverId": "e6d9b705-f537-47a8-bfc1-2dd2e9620013",
    "date": "20220223",
    "isApproved": false,
    "displayLabel": "1"
  }
Property Type Description
orderStepId OrderStepIdentifier The OrderStep ID
vehicleId UUID The Vehicle ID that the OrderStep is assigned to.
driverId UUID The Driver ID that is assigned to the Vehicle
date DateString The date in wich the OrderStep is assigned
isApproved boolean Indicates if the orderStep is part of an Approved route
displayLabel String Label shown in the web application for this OrderStep

Notification data objects

OrdersChanged Object properties

{
  "created": [
    {
      "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "geocodeStatus": {
        "delivery": "OK"
      },
      "pickup": null,
      "delivery": {
        "location": "OK",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    },
    {
      "id": "89009ba2-285f-47a1-8b91-5524d8f31b16",
      "geocodeStatus": {
        "delivery": "LOW_ACCURACY"
      },
      "pickup": null,
      "delivery": {
        "location": "LOW_ACCURACY",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    },
    {
      "id": null,
      "geocodeStatus": {
        "delivery": "NOT_FOUND"
      },
      "pickup": null,
      "delivery": {
        "location": "NOT_FOUND",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    },
    {
      "id": "3d499ad0-14f6-4a38-acd8-05b8269dec78",
      "geocodeStatus": {
        "delivery": "POSTCODE_ISSUE"
      },
      "pickup": null,
      "delivery": {
        "location": "POSTCODE_ISSUE",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    },
    {
      "id": "a5682ad9-97e8-4719-9bb6-eecfcfb8606b",
      "geocodeStatus": {
        "delivery": "OK",
        "pickup": "LOW_ACCURACY"
      },
      "pickup": {
        "location": "LOW_ACCURACY",
        "email": "VALID",
        "phone": "NOT_VALID"
      },
      "delivery": {
        "location": "OK",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    }
  ],
  "updated": [
    {
      "id": "aee94205-c434-4e6e-b4a5-a9466c8f19ca",
      "geocodeStatus": {
        "delivery": "OK"
      },
      "pickup": null,
      "delivery": {
        "location": "OK",
        "email": "VALID",
        "phone": "NOT_VALID"
      }
    }
  ],
  "deleted": [
    "a784cb3a-429d-4f74-b5e5-3e9528f37917",
    "88c51466-87bf-4fa4-be8a-e0bf0eab586f"
  ]
}
Property Type Description
created list of ChangedOrder details about the newly added Orders
updated list of ChangedOrder details about the updated Orders
deleted list of UUID UUIDs of removed Orders

ChangedOrder Object properties

{
  "id": "aee94205-c434-4e6e-b4a5-a9466c8f19ca",
  "geocodeStatus": {
    "delivery": "OK"
  },
  "pickup": null,
  "delivery": {
      "location": "NOT_FOUND",
      "email": "VALID",
      "phone": "NOT_VALID"
  }
}

{
  "id": "a5682ad9-97e8-4719-9bb6-eecfcfb8606b",
  "geocodeStatus": {
    "delivery": "OK",
    "pickup": "LOW_ACCURACY"
  },
  "pickup": {
      "location": "LOW_ACCURACY",
      "email": "VALID",
      "phone": "NOT_VALID"
  },
  "delivery": {
      "location": "OK",
      "email": "VALID",
      "phone": "NOT_VALID"
  }
}

// Order with a formal validation error
{
  "id": null,
  "error": {
    "errorCode": 102,
    "errorMessage": "orders[2].delivery.customFields has too many entries. The maximum number of per-order custom fields is 20"
  },
  "geocodeStatus": {
    "delivery": "OK"
  },
  "pickup": null,
  "delivery": {
    "location": "NOT_FOUND",
    "email": "VALID",
    "phone": "NOT_VALID"
  }
}

// Order with a delivery OrderStep that failed to be added because the address could not be geocoded
{
  "id": null,
  "geocodeStatus": {
    "delivery": "NOT_FOUND"
  },
  "pickup": null,
  "delivery": {
    "location": "NOT_FOUND",
    "email": "VALID",
    "phone": "NOT_VALID"
  }
}

//Order created in response to a SplitOrders operations
{
  "id": "5bd9a332-61de-47e7-9ffb-711901702b6c",
  "geocodeStatus": {
    "pickup": "OK"
  },
  "pickup": {
    "location": "OK",
    "email": "VALID",
    "phone": "VALID"
  },
  "delivery": null,
  "splitFromOrderId": "e01c1153-dd4c-4cb8-8eb4-62d2a344967d"
}
Property Type Description
id UUID OR null UUID of added or updated Order, null for Orders that failed to be added
geocodeStatus map[Type]Status [DEPRECATED] Type can be either pickup or delivery. Status is one of:
OK: success, and returned data indicates that the geocoded location is accurate
LOW_ACCURACY: success, but the location might not be accurate (e.g.: location on the correct street, but street number not found)
POSTCODE_ISSUE: success, but the postcode is either missing or does not match the one in the normalized address returned by the geocoding process
POSTCODE_LEVEL_ACCURACY: success, but the location is only accurate at the postcode level, not at the street level
OUT_OF_TERRITORY_RANGE: failure. Geocoding succeeded but the geocoded location is outside of the Territory’s area
NOT_FOUND: failure, address not found
GEOCODING_ERROR: failure, the geocoding service encountered a temporary error
GEOCODING_TIMEOUT: failure, the geocoding service took too long to respond
Note: Orders whose address cannot be geocoded are not added/updated.
For example, an Add Orders invocation adding 40 Orders where 5 fail to be geocoded will succeed but it will only add 35 Orders
pickup map[String]String Defined in case the pickup step exists, null otherwise. It contains the following keys, related to the pickup step validation: location (the same value of the deprecated geocodeStatus field), email and phone. email and phone values can be VALID or NOT_VALID, in case the contact data has been respectively formally validated (or null) or not. In case of NOT_VALID data, the eventual corresponding message to the customer will not be sent.
delivery map[String]String Defined in case the pickup step exists, null otherwise. It contains the following keys, related to the delivery step validation: location (the same value of the deprecated geocodeStatus field), email and phone. email and phone values can be VALID or NOT_VALID, in case the contact data has been respectively formally validated (or null) or not. In case of NOT_VALID data, the eventual corresponding message to the customer will not be sent.
splitFromOrderId String Defined in case of a notification triggered by a SplitOrders invocation. It contains the orderId that was split and removed to generate the new order.
error ErrorResponse OR null Error details in case of a formal validation error, null otherwise. Currently only populated by calls to Add Orders with the strict parameter set to false.

ExecutionEventsProcessed Object properties

{
  "processed": [
    "OK",
    "OK",
    "ERROR_VEHICLE_NOT_TRACKED",
    "OK_WARN_LATLNG_OUT_OF_BOUNDS",
    "OK"
  ]
}
Property Type Description
processed List of ProcessedStatus Details about the ExecutionEvents that have been submitted.
ProcessedStatus is one of:
OK: the event was accepted and processed
OK_WARN_LATLNG_OUT_OF_BOUNDS: the event was accepted and processed, but the attached coordinates have been ignored because they fall outside of the Territory bounds
POSTPONED: the event was queued and will be processed at a later time. This happens when a user-initiated editing transaction is in progress. Under those circumstances all submitted ExecutionEvents are queued and processed as soon as the editing transaction completes.
Note: if the property tracked of the Vehicle the event is associated with is set to false, the postponed event will be discarded and it will not be processed.
ERROR_NO_ORDER: the event was discarded because it references a non-existing Order
ERROR_NO_ORDER_STEP: the event was discarded because it references a non-existing OrderStep
ERROR_NO_VEHICLE : the event was discarded because it references a non-existing Vehicle
ERROR_VEHICLE_NOT_TRACKED: the event was discarded because it references a non-tracked Vehicle
ERROR_INVALID_EVENT_TYPE: the event was discarded because its type value is invalid
ERROR_VALIDATION: the event was discarded because of a generic formal validation issue

SchedulingCompleted Object properties

{
  "orderIds": [
    "603a348f-7fcc-4bdc-8f4a-ec10a68547e0"
  ],
  "orderSteps": [
    {
      "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "type": "delivery"
    }
  ],
  "outOfBorderOrderIds": ["3419b8f6-1767-4710-be3e-14d4ff614b57"]
}
Parameter Type Description
orderIds List of UUID List of affected Orders.
Only populated by Fit-in Unassigned Orders and Unassign Orders APIs. Not populated by Build Routes and SwapRoutes APIs
orderSteps List of OrderStepIdentifier List of affected OrdersSteps.
Only populated by the Assign an OrderStep API. Not populated by Build Routes and SwapRoutes APIs
outOfBorderOrderIds List of UUID List of unassigned Orders due to border restriction enabled in the territory.
Only populated by Fit-in Unassigned Orders API. Not populated by Build Routes and SwapRoutes APIs

UnassignOrderList Object properties

{
  "orderIds": [
    {
      "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
      "type": "delivery"
    }
  ]
}
Parameter Type Description
orderIds List of OrderStepIdentifier List of affected OrdersSteps.
Only used by the Unassign Orders V1 API.

ApprovedRoutesChanged Object properties

{
  "approved": [
    "20151204",
    "20151205"
  ],
  "revoked": [
    "20151206"
  ]
}
Property Type Description
approved list of DateString The list of dates where Routes have been approved, or where approval has been updated
revoked list of DateString The list of dates where Routes have been revoked approval

VehicleDriverAssignmentsChanged Object properties

{
  "requestId": "b32feaf9-5bbc-460a-9ee2-be68b9d648e4",
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
  "event": "vehicleDriverAssignmentsChanged",
  "data": {}
}

DriversChanged Object properties

{
  "created": [
    "0129724f-b80d-4011-ab91-3e4ae2f62896"
  ],
  "updated": [
    "a3935987-4944-462f-b602-4a3a12beeeff"
  ],
  "deleted": [
    "a08213e6-673f-4efc-955e-2bf587813162"
  ]
}
Property Type Description
created list of UUID UUIDs of created Drivers
updated list of UUID UUIDs of updated Drivers
deleted list of UUID UUIDs of deleted Drivers

TerritoryChanged Object properties

{
  "territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345"
}
Property Type Description
territoryId UUID id of the changed territory

VehiclesChanged Object properties

{
  "created": [
    "875cceab-0952-4101-9db3-e524dbec9a75"
  ],
  "updated": [
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
  ],
  "deleted": [
    "0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
  ]
}
Property Type Description
created list of UUID UUIDs of created Vehicles
updated list of UUID UUIDs of updated Vehicles
deleted list of UUID UUIDs of deleted Vehicles

CompaniesChanged Object properties

{
  "created": [
    "0c920b8e-e904-444c-8371-63cd62f5b1bb"
  ],
  "updated": [],
  "deleted": []
}
Property Type Description
created list of UUID UUIDs of created Companies
updated list of UUID UUIDs of updated Companies
deleted list of UUID UUIDs of deleted Companies

ProposalsSetProcessed Object properties

{
  "order": {
    "id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
    "geocodeStatus": {
      "delivery": "OK"
    }
  },
  "proposals": [
    {
      "status": "NOT_FOUND"
    },
    {
      "status": "FOUND",
      "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
      "pickupStartSec": 38265,
      "deliveryStartSec": 43549,
      "routeCost": 201675,
      "deltaCost": 10498
    },
    {
      "status": "NOT_FOUND"
    }
  ]
}
Parameter Type Description
order ChangedOrder Details about the Order specified in the Compute ProposalsSet request, namely the assigned id and geocoding status(es)
proposals list of ProposalSummary Overview data for each computed proposal.
Note: Size and item sequence of this array match the timeSlots array in the Compute ProposalsSet request

ProposalSummary Object properties

{
  "status": "FOUND",
  "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
  "pickupStartSec": 38265,
  "deliveryStartSec": 43549,
  "routeCost": 201675,
  "deltaCost": 10498
}
Parameter Type Description
status enum One of FOUND or NOT FOUND
routeId String Shown only if status is FOUND. ID of the Route where there is the best insertion for the Order following current proposal (timewindows + eligibility)
pickupStartSec int Service start time for the proposal pickup OrderStep, null if proposal order pickup OrderStep is null
deliveryStartSec int Service start time for the proposal delivery OrderStep, null if proposal order delivery OrderStep is null
routeCost int Monetary cost of the route associated with this proposal (the one reported within data field of Proposal object) or null if status is NOT_FOUND
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23
deltaCost int Monetary cost difference between the route associated with this proposal (the one reported within data field of Proposal object) and the original route without the Order subject of proposals, or null if status is NOT_FOUND
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23

ProposalApplied Object properties

{
  "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
  "routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
  "proposalIndex": 1
}
Parameter Type Description
orderId UUID ID assigned to the Order in the ProposalsSet
routeId UUID ID of the Route that the Order has been added to
proposalIndexApplied int Zero-based index of the applied proposal in proposals array of the ProposalsSet object

RegionsChanged Object properties

{
  "created": [
    "933c5158-517e-4234-a987-46c931914ac4"
  ],
  "updated": [
    "e01eb12b-f1c9-4982-9276-dee95f07c487"
  ],
  "deleted": [
    "6543c0c1-d55e-46e1-ae3c-65d26239351c"
  ]
}
Property Type Description
created list of UUID UUIDs of created Regions
updated list of UUID UUIDs of updated Regions
deleted list of UUID UUIDs of deleted Regions

Miscellaneous objects

LatLng Object properties

// Coords for the Arena in Verona, Italy
// https://www.google.com/maps/@45.439,10.994428,20z
[45439000, 10994428]

// Coords for St. Paul's Cathedral, London, UK
// https://www.google.com/maps/@51.513753726152,-0.098655,20z
[51513753, -98655]

[lat, lng] where lat and lng are computed as WGS-84 decimal coords * 1_000_000, rounded down to the nearest integer value.

Example #1:

Example #2:

DateString Object properties

// December 15, 2015
"20151215"

Date represented as a string formatted as yyyyMMdd.

Location Object properties

{
  "address": "3101 Florida Ave, Jasper, AL 35501, USA",
  "latLng": [
    33817872,
    -87266893
  ],
  "status": "OK",
  "geoAddress": "3101 Florida Ave, Jasper, AL 35501, USA",
  "countryCode": "US-AL"
}
Property Type Description
address String The full address, as provided
latLng LatLng The coordinates for the address
status enum Accuracy status computed during the geocoding process.
One of OK, LOW_ACCURACY, POSTCODE_ISSUE, POSTCODE_LEVEL_ACCURACY
If no geocode took place (e.g.: because coordinates were already provided along with the address) then status=OK
geoAddress String OR null The normalized address returned by the geocoding process
countryCode String The country code in format ISO-3166. Used and populated only if the territory is using the border restriction logic.

LocationInput Object properties

Address only: geocoding is performed to get the map coordinates together with an “accuracy” status

{
  "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA"
}

Address + coordinates: no geocoding takes place, the address is treated as a plain string and the “accuracy” status is assumed to be OK

{
  "address": "3101-3199 Florida Ave, Jasper, AL 35501, USA",
  "latLng": [33817872, -87266893]
}
Property Type Description
address String Mandatory: the full address, properly formatted as per postal service directives, and without additional non-standard details like apartment number, suite number and other notes
latLng LatLng Optional: the coordinates of the address. If left empty, the address is geocoded to retrieve its coordinates.
Note that geocoding cannot be guaranteed to always be 100% exact. For example, addresses for newly built roads that have not yet been added to our maps may fail to be geocoded or return “best-effort” coordinates. Wrongly formatted or partial addresses will also unlikely translate to precise coordinates

TimeWindow Object properties

{
  "startSec": 30600,
  "endSec": 37800
}
Property Type Description
startSec int Start of the time window in seconds since midnight
endSec int End of the time window in seconds since midnight. Must be >= startSec

Break Object properties

{
  "durationSec": 3600,
  "startSec": 28000,
  "endSec": 28800
}
Property Type Description
durationSec int Break duration in seconds
startSec int Earliest time when the break can start, in seconds since midnight
endSec int Latest time when the break can start, in seconds since midnight. Must be >= startSec

Eligibility Object properties

Eligible to be served on December 4 or December 5, 2015

{
  "type": "on",
  "onDates": [
    "20151204",
    "20151205"
  ]
}

Eligible to be served up to and including December 15 2015

{
  "type": "by",
  "byDate": "20151215"
}

Eligible to be served on any date

{
  "type": "any"
}
Property Type Description
type enum One of on, by, any
byDate DateString Used when type = by
onDates list of DateString Used when type = on

OrderStepIdentifier Object properties

{
  "orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
  "type": "delivery"
}
Parameter Type Description
orderId UUID Id of the Order. Together with type identifies the OrderStep
type enum One of pickup or delivery.
Note: OrderSteps belonging to “service” Orders (orders flagged with “isService=true”. See also the description of Order.isService) will have type=delivery

Fix Object properties

{
  "sec": 36512,
  "latLng": [
    33817872,
    -87266893
  ]
}
Property Type Description
sec int Fix time, in seconds since midnight
latLng LatLng OR null Fix coordinates, where available

ErrorResponse Object properties

{
  "errorCode": 600,
  "errorMessage": "Adding 75 Orders to the existing 980 exceeds the maximum of 1000 allowed for operations on territory [New York]"
}
Property Type Description
errorCode int One of the error codes listed here
errorMessage String A human-readable message providing additional details about the error

TrackedLoad Object properties

{
  "latLng": [
    33817872,
    -87266893
  ],
  "timeSec": 3900,
  "value": 19
}
Property Type Description
latLng LatLng Coordinates from wich the load was updated via Mobile App.
timeSec int Time, in seconds since midnight, when the load was updated (from the Mobile App).
value int The value set by the user.
Note: this field represents a decimal number. The value will be divided by 100. E.g.: 123 means 1.23

TrackedCustomFields Object properties

{
  "latLng": [
    33817872,
    -87266893
  ],
  "timeSec": 4200,
  "value": "ABCD"
}
Property Type Description
latLng LatLng Coordinates from wich the custom field was updated via Mobile App.
timeSec int Time, in seconds since midnight, when the custom field was updated (from the Mobile App).
value String The value set by the user.

Revision History

Date (Y/M/D) Description
 
2025/03/26 Update VehicleSettings object definition to manage maxLocations and maxStops.
Update SchedulingCompleted Object definition to notify unassigned Orders due to border restriction in Fit-In Unassigned Orders requests.
2025/01/22 Update Vehicle Objects definition to manage 3rd party providers integration.
2025/01/08 Added Sequential Fit
Added OrderStep Tracking Data Updated Notification. See OrderStep Tracking Data Updated Notification.
Deprecated Orderstep Tracking Data Update Notification OrderStep Tracking Data Update Notification.
2024/12/11 Add Same Side of Street option on Vehicle Object properties, VehicleFull Object properties and VehicleInput Object properties
2024/10/29 Update Drivers API to manage the new parameters summarizeFutureMobileRoute and mobileFutureDaysVisibility.
2024/10/09 Update AssignOrderStep and AssignOrderSteps documentation.
2024/06/19 Update Simulations REST APIs documentation.
2024/05/08 Update List GPS Devices and List Current GPS Info to manage 3rd party providers integrations
2024/04/17 Added support for Companies; modified Order and OrderInput to support companyId
2023/10/11 Added note about max tags limit to VehicleSettings Object properties, OrderStep Object properties and OrderStepInput Object properties
2023/09/27 Added note about horizon limit to Replace Vehicle Settings and Bulk Replace Vehicle Settings
2023/07/12 Added acceptBadGeocodes flag to Replace an Order, Replace Orders, Replace an OrderStep, Update an Order and Update Orders
2023/05/24 Added loadTracking and customFieldTracking events to Execution Events. Added trackedLoadMap and trackedCustomFieldMap to Tracking Data.
2022/12/14 Added preparationTimeSec and closeOutTimeSec fields to VehicleSettings. Added preparation and closeOut as types for RouteStep. Added preparationTimeIn, preparationTimeOut, closeOutTimeIn and closeOutTimeOut as types for Execution Event.
2022/11/29 Added WebHooks documentation.
2022/07/12 Added dates parameter to List Approved Routes and List Approved Routes v2.
2022/03/23 Added Add Depots and Delete Depots with object types and notifications.
Added Update Depots with object types and notifications.
Added Add Regions, Replace Regions and Delete Regions APIs with corresponding object types and notifications.
Added Unassign Orders V2 API and deprecated Unassign Orders API. Added UnassigneOrderList object.
Added strict parameters to Replace Orders
Added strict parameters to Update Orders
2021/10/13 Added ignoreRevision and costPercentThreshold parameters to Apply Proposal
2021/07/13 Added Update Vehicles Details
2021/02/08 Added Customer Notification API
2021/01/27 Added contact information validation. See ValidateContactInfo
2020/12/21 Added new pickup and delivery fields, deprecated geocodeStatus field in ChangedOrder object. email and phone contact information in OrderStepInput object and OrderStep object are now accepted even if formally invalid.
2020/12/02 Added missing documentation for the barcodes property in PodContainer
2020/10/14 Added support for status reasons. See the statusReasons field in Territory, the statusReason field in TrackingData, the statusReason field in EEDataStatusUpdate and Edit Territory
2020/03/16 Added support for barcodes. See the barcodes field in OrderStep and OrderStepInput, and the EEDataPodBarcodes object in the proofs of delivery.
2020/01/28 Added support for routes swapping. See SwapRoutes
2020/01/15 Added the minWorkingTimeSec and minLoadCapacities fields to Vehicle Settings. See VehicleSettings
2019/11/06 Added the settings field to Vehicle. See Vehicle
Added normal day interaction to Vehicle Settings APIs: Get Vehicle Settings, Replace Vehicle Settings and Bulk Replace Vehicle Settings
2019/09/19 Added the headers parameter to Set Callback URL
2019/03/08 Fixed wrong signature in HMAC verification example. It was “ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa” while it should have been “ihyCCfTHog7TDQYT4tQM5ISYSjEIaChSeJmIo3UMa%2BU%3D”
2019/01/30 Added email and phone field on OrderStep and OrderStepInput. See OrderStep and OrderStepInput
2018/09/19 Added error field on Changed Order, useful to identify failure reasons when bulk-adding Orders with strict set to false. See Changed Order and Add Orders
2018/08/24 Clarified what changes are considered as backward-compatible and how integreation code should deal with them. See Versioning and evolution
2018/07/20 Added new route tracking data and new Execution Events types departure and arrival.
See updated objects Route and Execution Event.
See new object TrackingDataRegistry
2018/07/05 Added stopIdx field on Route Step. See RouteStep
2018/03/07 Added a new bulk version of Assign OrderStep API. See Assign Multiple OrderSteps
Added a new Apply Sequences API. See Apply Sequences
Updated the experimental “Proposals” set of API with the possibility to define both pickup and delivery time windows for each TimeSlot.
Now Proposal and ProposalSummary include information about proposals Route costs.
See the Proposals API set overview
2018/02/14 Added support for creating and deleting Vehicles.
See Add Vehicles and Delete Vehicles
2018/02/07 Added eligibleOn and assignedOn filtering options to List Orders
Superseded Querystring inputs with Request Body input variants in Get Orders, Delete Orders and Unassign Orders (avoids Querystring length limitations)
Added bulk versions of Get Vehicle Settings and Replace Vehicle Settings.
See List Vehicle Settings and Bulk Replace Vehicle Settings
2018/01/17 Added support for approving and revoking specific Routes in addition to whole dates.
Introduces a new functioanlity that, under some very specific circumstances, may cause problems with existing integrations. Please read Why v2 for Approved Plans.
See also Approved Plans API v2
2018/01/10 Added support for a new VehicleSettings constraint maxOrders. VehicleSettings Object now includes a new maxOrders field and Route Object’s vehicleViolations field can now include a new OR violation code.
See VehicleSettings and Route
2017/11/15 Added violations field to returned Route and RouteStep Objects.
See vehicleViolations on Route Object properties and violations on RouteStep Object properties
2017/11/10 Added an option to include Routes with selected violations in Fit-In requests.
See includeRoutesWithViolations in Fit-In Unassigned Orders
2017/11/08 Send Execution Events API now supports a strict property that, when set to false, ignores invalid Events without causing the whole request to fail.
See Send Execution Events
Documented new ERROR_VALIDATION error code that may be returned as a result of invoking Send Execution Events with strict set to false.
See ExecutionEventsProcessed Object properties
2017/09/07 Added pseudocode exemplifing how to verify a signed callback.
See examples at Set Callback URL
Clarified that deleting one OrderStep from a pickup&delivery Order triggers an update order notification, not a delete one.
See examples at Delete an OrderStep
2017/08/03 Clarified routeIds property in BestFit request, clarified to/from limits in BestFit and BuildRoutes requests.
2017/05/24 Added a new “Proposals” set of API (experimental).
See the Proposals API set overview and the new Proposals API section.
2017/05/19 Added support for sending detected time-in and detected time-out Proof-of-Delivery (POD) items.
These two new POD types are intended to be used by customers implementing their own Mobile Application and requiring full control over all aspects of Event Tracking.
See updated Execution Event
2017/05/10 Fixed incorrect references and a couple of broken links
2017/01/26 Added support for sending audio-recording Proof-of-Delivery (POD) items.
See updated Execution Event and Audio POD object
Documented safe querystrings size limits on relevant methods.
See Get Orders and Delete Orders
Documented missing limitations on binary Proof Of Delivery items (images, pictures and audio recordings).
See Signature POD object, Picture POD object and Audio POD object
2017/01/13 Clarified that tags and load names can only be lowercase and are lowercased on input.
See OrderInput, OrderStepInput and VehicleSettings
2016/12/27 Added timeInDetected and timeOutDetected fields to the TrackingData Object.
See TrackingData Object
Added clarifications on how time-in, time-out, status-update and proof-of-delivery events are taken into account when updating ETAs of yet-to-be-serviced Orders.
See Send Execution Events
2016/12/14 Added support for assigning an OrderStep to a Route at a given position.
See Assign an OrderStep and SchedulingCompleted Object
2016/11/22 Documented missing limitations in OrderInput, OrderStepInput and VehicleSettings Objects.
See OrderInput, OrderStepInput and VehicleSettings
2016/09/22 Fixed incorrect references. Order Object pickup and delivery properties now correctly listed as OrderStep-type Objects
Consistency: renamed objects InputOrder to OrderInput and InputDriver to DriverInput (no impact on existing integrations)
2016/09/15 Fixed incorrect URL at List Current GPS Info
2016/07/20 Fixed incorrect example and non-working link at Approve Routes
2016/06/27 Added support for Time Window Exceptions. OrderStep Object now includes a timeWindowExceptions field.
See the OrderStep Object
2016/06/18 Added a new “GPS Tracking” set of API. See here and here.
Drivers can now be associated to a GPS Device. Driver and Vehicle Objects now include a gpsDeviceId field.
See DriverInput Object, Driver Object and Vehicle Object
2016/05/10 Added support for a new VehicleSettings constraint maxDistanceMt. VehicleSettings Object now includes a maxDistanceMt field
2016/05/03 Add Orders API now supports a acceptBadGeocodes property that, when set to true, allows all Orders to be added to the plan, regardless of the outcome of the geocoding process. Orders with an invalid address can be later manually reviewed/fixed from the Web Application. See Add Orders
2016/04/20 Added support for editing Vehicle settings, including availability. Introduces a new asynchronous notification.
See Replace Vehicle Settings and VehiclesChanged Notification
Added support for overriding UI-defined locked Routes in Build Routes and Fit-In API.
See lockedRouteIdsOverride in Build Routes and overrideLockedRoutes in Fit-In Unassigned Orders
Added support for CRUD operations on Drivers. Introduces a new asynchronous notification.
See Drivers API and DriversChanged Notification
Added a new “Vehicle-Driver Assignments” set of API. Introduces a new asynchronous notification.
See Vehicle-Driver Assignments API and VehicleDriverAssignmentsChanged Notification
Added Approve Routes and Revoke Routes API. Introduces a new asynchronous notification.
See Approve Routes, Revoke Routes and ApprovedRoutesChanged Notification
Added List Regions API. VehicleSettings Object now includes a regionIds field.
See List Regions and VehicleSettings
Fixed requestId property not being set to null on asynchronous notifications triggered by manual operations performed via the Web Application
Fixed error codes returned by failed validation checks on ReplaceOrders, BestFit and BuildRoutes APIs (returned errorCode 400 instead of 100)
2016/04/11 Added a new Replace Orders API. See Replace Orders
2016/04/08 Add Orders API now supports a strict property that, when set to false, ignores invalid Orders without causing the whole request to fail. See Add Orders
Added support for testing the callback URL. See the new test property at Set Callback URL
Added support for signing the the callback URL. See the new signaturePassword property at Set Callback URL
2016/03/09 Added List Drivers API
2016/02/29 Documentation migrated to HTML format. Fixed typos and errors in JSON example data. Added per-object JSON examples
2016/02/26 Updated the documentation to reflect the new product name (Fleet renamed to Route Manager). No functional changes have been introduced
2016/01/29 Clarified how Add Orders behaves in case of validation errors. See Add Orders
Relaxed throttling limits on List Approved Routes, Get Approved Route, List Current Routes, Get Current Route
2016/01/05 Added support for sending and retrieving Proof-of-Delivery (POD) items.
Retrieving PODs: see Download a Proof of Delivery. New pods field in TrackingData, new objects here and here
Sending PODs: see Send Execution Events, updated Execution Event, new objects here, here and here
2015/12/22 List Current Routes and List Approved Routes can now retrieve data from archived dates
2015/12/18 Improved documentation of query string parameters
2015/12/17 Improved JSON examples and fixed Add Orders request example (Single Order)
2015/11/13 Added Request/Response JSON examples
2015/11/11 Fixed description of the depot property in List Orders and Get Orders
2015/11/02 Added a new “Scheduling” set of API. See Scheduling API
2015/10/23 Added SendExecutionEvent API
2015/10/16 Implemented missing Replace an Order and Replace an OrderStep APIs.
Updated Depot, Vehicle and VehicleFull objects to include the color property.
Updated the include filter of the List Orders API to accept aliases of served/unserved: assigned/unassigned
2015/10/15 Fixed incorrect endpoint URLs
2015/09/29 Improved descriptions at Object Definitions
Removed a Chapter documenting a feature not yet available
2015/09/23 Added clarifications about service-type Orders here, here and here
2015/08/31 First public revision

Upcoming changes

No upcoming changes planned





























































 

http+json shell