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"
    }
  }
}

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",
      "email": "driver1@example.com"
    },
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "id": "a08213e6-673f-4efc-955e-2bf587813162",
      "name": "Driver 2",
      "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"
}

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)"
}

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

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,
      "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,
        "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,
      "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,
      "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
      }
    }
  ]
}

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

{
  "settings": {
    "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
      "externalId": "Test Vehicle"
    },
    "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,
      "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,
          "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,
          "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,
          "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": {
    "a08213e6-673f-4efc-955e-2bf587813162": {
      "id": "a08213e6-673f-4efc-955e-2bf587813162",
      "name": "Driver 2",
      "email": "driver2@example.com"
    },
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "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,
      "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": 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,
          "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",
      "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,
          "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,
          "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,
          "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": { }
}

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,
          "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": 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,
          "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,
      "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,
          "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,
      "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,
          "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",
      "email": "driver2@example.com"
    },
    "a3935987-4944-462f-b602-4a3a12beeeff": {
      "id": "a3935987-4944-462f-b602-4a3a12beeeff",
      "name": "Driver 1",
      "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

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,
        "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": {}
          }
        }
      },
      "driver": {
        "id": "a3935987-4944-462f-b602-4a3a12beeeff",
        "name": "Driver 1",
        "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,
        "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": {
              "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",
        "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"
        }
      }
    }