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
SSL/TLS is supported (and highly recommended)
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:
int
data: the maximum allowed value is2147483647
, the minimum allowed value is-2147483648
long
data: the maximum allowed value is9223372036854775807
, the minimum allowed value is-9223372036854775808
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:
- via the key query-string parameter
- via the X-WorkWave-Key HTTP header
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:
- Responses for asynchronous requests initiated via API
- Data-change notifications triggered via API (by any API actor, in case there is more than one)
- Data-change notifications triggered by users logged into the Web Application
- Availability of new approved Routes
- Changes in currently approved Routes
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.
- 200 OK: Success!
- 400 Bad Request: The request cannot be accepted. The accompanying error message explains why
- 401 Unauthorized: Authentication credentials are missing or incorrect
- 404 Not Found: The URI requested is invalid or the resource requested does not exists
- 429 Too Many Requests: Rate limit exceeded. Wait before retrying and reduce the rate of requests
- 500 Server Error: Something bad and unexpected happened, typically a bug or an unplanned maintenance update. The WorkWave support team is automatically alerted when this error happens but you may wish to contact them directly to provide additional details to help in the resolution
- 502 Bad Gateway: WorkWave Route Manager service is temporarily down or being upgraded
- 503 Service Unavailable: The WorkWave Route Manager servers are up, but overloaded with requests. Try again later
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:
- 100: Malformed Request: Something is wrong with the request. It could be that the JSON data in the request body is malformed (typically due to a missing or overabundant parenthesis or comma) or a mandatory field is missing or a negative value has been set for a field that expects a positive integer, etc.
- 102: Limit Exceeded: The request is formally correct but some limit has been exceeded (e.g.: trying to add an Order specifying more than 4 time windows)
- 400: Object Not Found: A request is trying to update an object that does not exist (e.g.: updating an Order with an unknown orderId)
- 500: Internal Error: An unexpected internal error happened that prevented the request to be fully completed. The status of the request is undefined
- 600: Licensing Limit Exceeded: The request is formally correct but a licensing limit has been exceeded (e.g.: trying to add 20 Orders to an Operations plan with 990 Orders when the licensing limit is 1000 Orders max)
- 800: Object In Use: Object already in use (e.g.: trying to create a new Driver with an email already in use by another Driver)
- 900: Scheduling Operation Already In Progress: Another scheduling operation is being processed at this moment. Please retry later
- 1203: Editing Transaction Active: The change-request cannot be accepted at this time because a user-initiated editing transaction is in progress
- 1401: Password too weak: The password provided within request does not accomplish the minimum required strength. Please use a more complex password
- 1600: Unauthorized: Account Not Active: The request cannot be accepted because the account is temporarily disabled or suspended
- 1601: Unauthorized: No API Access: API access is disabled for the account
- 1602: Unauthorized: Unknown API key: The API key does not exists
- 1603: Unauthorized: Malformed API key: The API key is not formatted as a valid UUID
- 1604: Unauthorized: Missing API key: The request does not include an API key
- 2000: Callback Server Failure: The callback server did not respond as expected. See Set Callback URL
- 1700: Proposals Concurrency Limit Exceeded: ProposalsSet computation request cannot be executed because the limit of allowed concurrent computations has been reached
- 1701: Proposals Storage Limit Exceeded: ProposalsSet computation request cannot be executed because the limit of allowed saved ProposalsSets has been reached
- 1702: Proposals TimeSlots Limit Exceeded: ProposalsSet computation request cannot be executed because it contains too many TimeSlots
- 1800: Plan Busy: A request that is supposed to be executed immediately cannot be accepted at this time because a long-running task is already in progress (e.g. optimization, reschedule, geocoding, bulk orders update or addition, etc). Please try later
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:
- sending field-updates (e.g.: gathered from a mobile application) about time-in and time-outs at an Order’s location and Order completion status
- automated notifications to end-users about ETA updates concerning their Order
- automated alerts about delays or human errors (e.g.: Orders being skipped or not being fulfilled according to the expected sequence)
- dashboard providing an overview of the current status
- reporting tools collecting statistics about average delays, order fulfillment ratios, etc.
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:
- automated dispatching of approved route plans to mobile apps and 3rd parties
- planned vs. actual route analytics
- 3rd parties planned vs. actual applications
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:
- automated daily optimization of next-day Orders/Routes
- automated best-fitting of new Orders into existing Routes
- automated rescheduling of “skipped” or “to be rescheduled” Orders (i.e.: assigned to today’s Routes but not served for some reason at the end of the day) to a later date
- automated fit-in of an unassigned Order to a specific Route at a desired position
- automated re-assignment of an Order from its current Route and position to a different (or same) Route and position (the UI-equivalent of Dragging & Dropping Orders in the scheduler)
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:
- smarter automated call-ahead solutions
- geofencing
- gps-breadcrumbs and last-position visualization
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:
- Consumer-facing portals where to show multi-slot availability based on consumer request.
- Home Delivery / eCommerce deliveries
- Field Services appointment booking
- Prioritizing and incentivizing historically “slower” days/delivery slots based on updated real-time fleet capacity
- Grocery delivery
- White Glove delivery
- Services / installation scheduling
Helper API sets
In addition to the core API sets, the following additional helper REST resources are available:
- Callback API: to set and update the callback URL
- Territories API: to list the available territories
- Depots API: to list depots
- Regions API: to list regions
- Drivers API: to do CRUD operations on drivers
- Vehicles API: to list, get and update available vehicles
- Vehicle-Driver Assignments API: to get and set assignments on a per-date basis
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:
wwrm-api-key
: Your API key, which can be retrieved logging into Route Manager and navigating to “Account Settings”, then “API Integration”wwrm-territoryId
: The territoryId used by almost all calls. Call “List Territories” to get a list of available Territory IDswwrm-routeId
: The routeId, used by a number of endpoints. Call “List Current Routes” or “List Approved Routes” to get a list of available route IDs for the configured Territory
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 |
---|---|---|
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 |
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 |
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
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 POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/vehicles/details?key=AUTH_KEY
POST /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
POST 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 vehicleId s and values are the associated driverId s |
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
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"
}
}
}
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
}
]
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 |
orders | list of Order | List of replacement Orders |
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": {}
}
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
}
]
}
}
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,
}
}
]
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 |
orders | list of Order | List of replacement Orders |
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 |
Time Of Arrival API
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:
- a time-in: the actual time when the Order starts being serviced, typically intended as reported by a Driver
- a time-out: the actual time when service at the Order is completed, typically intended as reported by a Driver
- a detected time-in: the detected time when the Order starts being serviced, typically intended as automatically detected by a Mobile Application (via geofencing rules or more advanced heuristics)
- a detected time-out: the detected time when service at the Order is completed, typically intended as automatically detected by a Mobile Application (via geofencing rules or more advanced heuristics)
- a time-out: the actual time when the Order is completed (typically intended as reported by a Driver)
- a status-update: flags the Order as “done” or “to be rescheduled” (typically intended as reported by a Driver)
- a proof-of-delivery: record a proof-of-delivery item such as:
- a note: a generic text note. Only one note per OrderStep is supported
- a picture: a png or jpg image. Multiple pictures per OrderStep are supported
- a signature: a png or jpg image. Both “driver” and “customer” signatures are supported
- an audio recording: a mp3 or aac recording. Multiple audio recordings per OrderStep are supported
- the list of barcodes scanned for this Order
- a departure: the actual time when a driver starts its working time
- an arrival: the actual time when a driver ends its working time
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)
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:
- creates a “snapshot” of the planned Routes for that date, which can be later compared to their executed status
- makes Routes visible to mobile applications
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:
- 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
- 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
- Update Order O1 increasing its service time to 30 minutes
- 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"
}
}
}
]
}
List approved planned Routes (synchronous).
Approved Routes define routes as they where, “frozen” at the time of their approval for execution, therefore they only contain ETAs.
They serve as a “snapshot” of how the Route had originally been planned and how it was supposed to be executed, to be used as reference and/or to be compared with the actual, executed-in-the-real-world version of the same Route.
An approved Route can be revoked or updated and re-approved, up until an Execution Event (time-in, time-out, etc) is captured by the system about an Order serviced by the Route. At that point it is not possible to revoke or update the approved Route anymore.
THROTTLING
Rate-limit (1 call every minute)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v2/territories/:territoryId/approved/routes[?date=today|<yyyyMMdd>&dates=<yyyyMMdd>,<yyyyMMdd>]
QUERYSTRING PARAMETERS
Property | Type | Description |
---|---|---|
date | DateString OR “today” | Get all Approved Routes for the given date (defaults to “today”). Note:This input field is deprecated. |
dates | Comma separated list of DateString | Optional. If populated will override the “date” field. Get all Approved Routes for the given dates. |
RETURN VALUES
Property | Type | Description |
---|---|---|
approvedRoutes | list of ApprovedRoute | A list of ApprovedRoute |
Get Approved Route v2
Get an approved planned Route (synchronous).
THROTTLING
Leaky bucket (size:10, refill: 6 per minute)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v2/territories/:territoryId/approved/routes/:routeId
RETURN VALUES
ApprovedRoute Object
Approve Routes v2
curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
{
"ids": [
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204",
"0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151204",
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151205"
],
"strict": false
}
The above command returns JSON structured like this:
{
"requestId": "761ce1c6-3336-4e00-8296-5d1885b0ad4d"
}
And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:
{
"requestId": "761ce1c6-3336-4e00-8296-5d1885b0ad4d",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "approvedRoutesChanged",
"data": {
"approved": ["20151204", "20151205"],
"revoked": []
}
}
Approve (or update approval of) the given Routes (asynchronous).
Approving Routes:
- creates a “snapshot” of the planned Routes, which can be later compared to their current/executed version
- makes Routes visible to mobile applications
THROTTLING
Leaky bucket (size:3, refill: 1 per minute)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v2/territories/:territoryId/approved
REQUEST BODY
Property | Type | Description |
---|---|---|
ids | list of String | List of routeIds to be approved. Note: approving an empty Route is the same as revoking its approval. Note: unless strict is set to false, a routeId that is malformed, or referencing a non-existing vehicle, or a date further than the allowed horizon, or a Route that is being executed, or a Route whose approval would exceed the limits, causes the request to fail.LIMITS: excluding dates in the past and today, there can be only 3 future dates with one or more approved Routes. Approving one or more Routes on a 4th future date causes the request to fail (unless strict is false, in which case routeIds referencing dates in excess of the limit are ignored). |
strict | boolean | Optional, defaults to true. When set to false causes invalid routeIds to be silently ignored without making the request fail |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to approvedRoutesChanged |
data | ApprovedRoutesChanged OR ErrorResponse | The list of dates where Routes have been approved, or where approval has been updated |
Revoke Routes v2
curl -H "Content-Type: application/json" -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved?key=AUTH_KEY
DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/approved HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
{
"ids": [
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151205"
]
}
The above command returns JSON structured like this:
{
"requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82"
}
And triggers an ApprovedRoutesChanged Notification (POSTed to the callback URL) structured like this:
// If after revoking the given routeIds there are no more approved Routes on 2015-12-05:
{
"requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "approvedRoutesChanged",
"data": {
"revoked": ["20151205"]
}
}
// If after revoking the given routeIds there is still one or more approved Routes on 2015-12-05,
// and to indicate that the approval status of Routes for 2015-12-05 changed:
{
"requestId": "85ab72d2-ac04-4a37-b07f-74bb75c65a82",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "approvedRoutesChanged",
"data": {
"approved": ["20151205"]
}
}
Revoke approval for the given Routes (asynchronous).
THROTTLING
Leaky bucket (size:3, refill: 1 per minute)
HTTP REQUEST
DELETE https://wwrm.workwave.com/api/v2/territories/:territoryId/approved
REQUEST BODY
Property | Type | Description |
---|---|---|
ids | list of String | List of routeIds whose approval must be revoked. Note: invalid routeIds are ignored |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to approvedRoutesChanged |
data | ApprovedRoutesChanged OR ErrorResponse | The list of dates where Routes have been revoked approval |
Scheduling API
Build Routes
curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/buildroutes?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/buildroutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"from": "20151204",
"to": "20151207"
}
The above command returns JSON structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {}
}
(Re)build Routes with the goal of serving all Orders eligible in the given date-range minimizing the overall cost (asynchronous).
The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Full Optimization” option.
THROTTLING
Rate-limit (1 call every 1 minute)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/buildroutes
REQUEST BODY
Property | Type | Description |
---|---|---|
from | DateString | Inclusive |
to | DateString | Inclusive. Must be >= from . Must not exceed the allowed optimization horizon. |
lockedRouteIdsOverride | list of String | Optional list of routeIds. Defaults to null. If null UI-defined locks are honored. If not null UI-defined locks are ignored and replaced with those from this list. The scope of the override is limited to the request (UI-defined locks are left unchanged) |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Fit-In Unassigned Orders
curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/fitin?key=AUTH_KEY
POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/fitin HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"from": "20151204",
"to": "20151204",
"orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"],
"includeRoutesWithViolations": "none"
}
The above command returns JSON structured like this:
{
"requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "3dad8065-2c06-44ce-a4d8-c8a079b895a6",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderIds": ["603a348f-7fcc-4bdc-8f4a-ec10a68547e0"]
}
}
Fit unassigned Orders into Routes in the given date-range minimizing the overall cost and preserving existing Vehicle-Route assignments (asynchronous).
The behavior is equivalent to expanding the “Build Routes” dropdown button from within the WorkWave Route Manager Web Application and selecting the “Fit In unassigned Orders” option.
If Orders cannot be fit into existing routes but unused Vehicles are available, they will be used.
THROTTLING
Rate-limit (1 call every 20 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/fitin
REQUEST BODY
Property | Type | Description |
---|---|---|
from | DateString | Inclusive |
to | DateString | Inclusive. Must be >= from . Must not exceed the allowed optimization horizon |
orderIds | list of String | Optional. Ids of eligible, unassigned Orders that should be fitted in. If null or empty the system will try to fit-in all unassigned Orders that are eligible in the given date range |
routeIds | list of String | Optional. If provided, the system tries to fit Orders only in the given Routes. If null or empty the system will try to fit Orders in any available Route (existing or new) matching the given from /to date range. If specified overrides from /to preperties. |
overrideLockedRoutes | boolean | Optional. Defaults to false. If set to false UI-defined locks are honored. If set to true UI-defined locks are ignored (i.e.: all Routes and Vehicles matched by the date range and by routeIds become eligible targets for fitting in unassigned Orders regardless of UI-defined locks) |
includeRoutesWithViolations | enum | One of none or vehicleOrderAssignment .Optional. Defaults to none .If set to none existing Routes that violate one or more constraints are excluded from the list of eligible fit-in targets.If set to vehicleOrderAssignment existing Routes where already-assigned Orders violate one or more of the following constraints are considered eligible fit-in targets: tag, region, date eligibility, forced vehicle assignment.Note: selecting this option still ensures that no additional violations are generated (i.e.: unassigned Orders that are fit-in to some Route as a result of this this request will not violate any constraint) |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Unassign Orders [Deprecated]
curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign?key=AUTH_KEY
POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"orderIds": [
"603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
"16836b9f-f059-4520-8554-74eeb63e5797"
]
}
The above command returns JSON structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderIds": [
{
"orderId": "603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
"type": "delivery"
},
{
"orderId": "16836b9f-f059-4520-8554-74eeb63e5797",
"type": "delivery"
}
]
}
}
Unassign Orders from their current routes, clearing their tracking data (asynchronous).
THROTTLING
Rate-limit (1 call every 20 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/unassign[?orderIds=<comma_separated_list>]
REQUEST BODY
Property | Type | Description |
---|---|---|
orderIds | list of String | Mandatory. List of one or more Orders to unassign. |
QUERYSTRING PARAMETERS
Property | Type | Description |
---|---|---|
orderIds | comma-separated list of String | Mandatory. List of one or more Orders to unassign. LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body. |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | UnassignOrderList OR ErrorResponse |
Assign an OrderStep
curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
The above command returns JSON structured like this:
{
"requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f"
}
And, if the OrderStep is successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderSteps": [
{
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
}
]
}
}
Or, if the OrderStep could not be (re)assigned, like this:
{
"requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderSteps": [
]
}
}
Assign an OrderStep to the given Route at the given position in time, updating ETAs accordingly (asynchronous).
If the OrderStep is presently assigned to a different Route, ETAs for both involved Routes are updated.
Note: It is not allowed to assign an OrderStep to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.
THROTTLING
Leaky bucket (size:20, refill: 1 per second)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/assign/:orderId/:orderStepType/to/:routeId/after/:sec
PATH PARAMETERS
Property | Type | Description |
---|---|---|
orderId | UUID | Identifies the Order |
orderStepType | enum | Identifies the OrderStep. Can be pickup or delivery |
routeId | String | Identifies the target Route. A target Route is created if it does not already exist. |
sec | int | The time, in seconds since midnight, after which the OrderStep should be positioned. Set it to 0 to assign the OrderStep at the beginning of the Route. Note: The system uses the provided time to figure out where, in the current sequence, the OrderStep needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderStep is scheduled might end up being different. |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Assign Multiple OrderSteps
curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/assign/to/31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151204/after/20342 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"orderSteps": [
{
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
},
{
"orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
"type": "delivery"
}
]
}
The above command returns JSON structured like this:
{
"requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e"
}
And, if OrderSteps are successfully (re)assigned, triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderSteps": [
{
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
},
{
"orderId": "9437fd40-6e4b-43ed-b8f8-cad1a03fe26f",
"type": "delivery"
}
]
}
}
Or, if the OrderSteps could not be (re)assigned, like this:
{
"requestId": "b63d9b84-7ce5-4704-bc85-251ee5277b1e",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderSteps": [
]
}
}
Assign one or more unassigned OrderSteps to the given Route starting at the given position in time, updating ETAs accordingly (asynchronous).
Limitations:: contrary to the single (re)assignment method, none of the referenced OrderSteps can be already assigned to existing Routes, therefore this method cannot be used to move/reassign OrderSteps from one Route to another.
Note: It is not allowed to assign OrderSteps to a position that is in the past, i.e.: before the maximum time recorded by any one of the Execution Events associated to OrderSteps assigned to the target Route.
THROTTLING
Leaky bucket (size:10, refill: 1 per 20 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/assign/to/:routeId/after/:sec
PATH PARAMETERS
Property | Type | Description |
---|---|---|
routeId | String | Identifies the target Route. A target Route is created if it does not already exist. |
sec | int | The time, in seconds since midnight, after which the list of OrderSteps should be positioned. Set it to 0 to assign the OrderSteps at the beginning of the Route. Note: The system uses the provided time to figure out where, in the current sequence, the list of OrderSteps needs to be inserted, and then reschedules the target Route adjusting ETAs to take into account driving times, time windows, etc…, therefore the actual time where the OrderSteps are scheduled might end up being different. |
REQUEST BODY
Property | Type | Description |
---|---|---|
orderSteps | list of OrderStepIdentifier | Mandatory. List of one or more OrderSteps to be assigned to the target route at the given time (and in the given sequence). |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Apply Sequences
curl -X POST https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/applysequences?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/applysequences HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"sequences": [
{
"routeId": "0d8855e6-28a0-4e89-9c67-b44c66c39ba6-20151207",
"orderSteps": [
{
"orderId": "49269a16-479c-4531-8ffd-513b7ccd0621",
"type": "delivery"
},
{
"orderId": "0dd9cab0-d1db-45de-b291-31a0b66d5562",
"type": "pickup"
}
]
},
{
"routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151207",
"orderSteps": [
{
"orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
"type": "pickup"
},
{
"orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
"type": "delivery"
}
]
}
]
}
The above command returns JSON structured like this:
{
"requestId": "28193dc3-557a-4b41-b122-7b97c7e72992"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "28193dc3-557a-4b41-b122-7b97c7e72992",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {}
}
Create new Routes based on the given sequences of OrderSteps (asynchronous).
Contrary to Build Routes no optimization is involved and the system strictly honors the given sequences limiting its role to computing ETAs based on estimated driving times and attempting to limit time-constraints violations (like Orders’ Time Windows) where possible.
This method is somewhat similar to Assign Multiple OrderSteps but differs from it in that it can create multiple Routes with one single request, but new Routes only, it does not allow assigning to existing Routes.
As with the multiple assignment method none of the referenced OrderSteps can be already assigned to existing Routes, therefore it cannot be used to move/reassign OrderSteps from one Route to another.
THROTTLING
Rate-limit (1 call every 60 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/applysequences
REQUEST BODY
Property | Type | Description |
---|---|---|
sequences | list of RouteSequence | Mandatory. List of one or more Sequences. LIMITS: Routes referenced by RouteSequence objects MUST be empty, and listed OrderSteps MUST NOT be already assigned to existing Routes |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Swap Routes
curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/swaproutes?key=AUTH_KEY
POST /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/swaproutes HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"srcRouteId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"dstRouteId": "3d1f37d0-aef6-4e7f-9c2b-1377d12c0fd0-20151203"
}
The above command returns JSON structured like this:
{
"requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "13251bf3-92fa-40f3-add2-6cf5d57534cc",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {}
}
Swap the orderstep sequences between two routes, moving the sequence of the first route on the second one and vice versa (asynchronous).
The behavior is equivalent to the “Swap” functionality of the WorkWave Route Manager Web Application.
THROTTLING
Rate-limit (1 call every 20 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/swaproutes
REQUEST BODY
Property | Type | Description |
---|---|---|
srcRouteId | String | routeId of the first route included within the process |
dstRouteId | String | routeId of the second route included within the process |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Get Progress
curl -H "Content-Type: application/json" -X GET -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/progress?key=AUTH_KEY
GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/progress HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"progress": 75
}
Returns the progress of a “Build Routes” ot “Fit-in” optimization currently running in a territory. If there are no running optimizations for the given territory it will respond with a 404 status (even if there is an optimization queued). The optimization could have been started either via API or from the UI.
THROTTLING
Leaky bucket (size:20, refill: 1 per second)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/territories/:territoryId/scheduling/progress
RETURN VALUES
Property | Type | Description |
---|---|---|
progress | int | Optimization progress percentage (0 - 100) |
Scheduling API v2
Unassign Orders v2
curl -H "Content-Type: application/json" -X POST https://wwrm.workwave.com/api/v2/territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign?key=AUTH_KEY
POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/scheduling/unassign HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"orderIds": [
"603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
"16836b9f-f059-4520-8554-74eeb63e5797"
]
}
The above command returns JSON structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a"
}
And triggers a SchedulingCompleted Notification (POSTed to the callback URL) structured like this:
{
"requestId": "ea261eca-59b1-4151-8883-4b504d43241a",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderIds": [
"603a348f-7fcc-4bdc-8f4a-ec10a68547e0",
"16836b9f-f059-4520-8554-74eeb63e5797"
]
}
}
Unassign Orders from their current routes, clearing their tracking data (asynchronous).
THROTTLING
Rate-limit (1 call every 20 seconds)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v2/territories/:territoryId/scheduling/unassign[?orderIds=<comma_separated_list>]
REQUEST BODY
Property | Type | Description |
---|---|---|
orderIds | list of String | Mandatory. List of one or more Orders to unassign. |
QUERYSTRING PARAMETERS [DEPRECATED]
Property | Type | Description |
---|---|---|
orderIds | comma-separated list of String | Mandatory. List of one or more Orders to unassign. LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. For backward compatibility only. Please pass the list via Request Body. |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification) |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse |
Customer Notifications API
List OrderStep Notifications
curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery?key=AUTH_KEY
GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders/fb5e269b-9a16-4d44-abe5-a3f1c84acdb7/delivery HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"notifications": [
{
"orderStepId": {
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
},
"kind": "SMS",
"sentTs": 1610115318405,
"status": "SENT",
"subject": null,
"recipient": "+11111111111"
"bodyPlainText": "Your order #123456 from Company XYZ will be delivered today",
"bodyHtml": null,
"errorCode": null,
"errorName": null
}
]
}
List the notifications that have been generated for an OrderStep. To fetch notifications in bulk for more that a few orders please use the List Orders Notifications API.
THROTTLING
Rate-limit (2 calls every second)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/territories/:territoryId/notifications/orders/:orderId/:orderStepType
RETURN VALUES
Property | Type | Description |
---|---|---|
notifications | list of OrderStepNotification | Notifications sent for the specified order step |
List Orders Notifications
curl https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders?key=AUTH_KEY&from=2021-01-07T00%3A00%3A00Z&to=2021-01-10T00%3A00%3A00Z
GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/notifications/orders?from=2021-01-07T00%3A00%3A00Z&to=2021-01-10T00%3A00%3A00Z HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"notifications": [
{
"orderStepId": {
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
},
"kind": "SMS",
"sentTs": 1610115318405,
"status": "SENT",
"subject": null,
"recipient": "+11111111111",
"bodyPlainText": "Your order #123456 from Company XYZ will be delivered today",
"bodyHtml": null,
"errorCode": null,
"errorName": null
}
]
}
List the notifications for all the orders in a territory. The list is restricted to the period of time
specified via the from
and to
query-string parameters, and can span a maximum of 7 days.
THROTTLING
Rate-limit (1 call every 10 minutes)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/territories/:territoryId/notifications/orders?from=YYYY-MM-DDThh:mm:ssZ&to=YYYY-MM-DDThh:mm:ssZ
QUERYSTRING PARAMETERS
Property | Type | Description |
---|---|---|
from | String | ISO 8601 timestamp |
to | String | ISO 8601 timestamp |
RETURN VALUES
Property | Type | Description |
---|---|---|
notifications | list of OrderStepNotification | Notifications sent for the specified order step |
Proposals API
Compute ProposalsSet
curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals?key=AUTH_KEY
POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"order":
{
"name": "Order coming from Proposals API",
"loads": {
"pounds": 400
},
"pickup": {
"location": {
"address": "100 20th Street West, Jasper, AL 35501, USA"
},
"notes": "Order (pickup) for which we want to compute a set of proposals",
"serviceTimeSec": 1800,
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"delivery": {
"location": {
"address": "2001 2nd Ave, Jasper, AL 35501, USA"
},
"notes": "Order (delivery) for which we want to compute a set of proposals",
"serviceTimeSec": 1800,
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"isService": false
},
"timeSlots": [
{
"pickupTimeWindows": [
{
"startSec": 18000,
"endSec": 19800
}
],
"deliveryTimeWindows": [
{
"startSec": 19800,
"endSec": 21600
}
],
"date": "20151204"
},
{
"pickupTimeWindows": [
{
"startSec": 45000,
"endSec": 46800
}
],
"deliveryTimeWindows": [
{
"startSec": 46800,
"endSec": 50400
}
],
"date": "20151204"
},
{
"pickupTimeWindows": [
{
"startSec": 18000,
"endSec": 19800
}
],
"deliveryTimeWindows": [
{
"startSec": 19800,
"endSec": 21600
}
],
"date": "20151205"
}
],
"overrideLockedRoutes": true
}
The above command returns JSON structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0"
}
And triggers a ProposalsSetProcessed Notification (POSTed to the callback URL) structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "proposalsSetProcessed",
"data": {
"order": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"geocodeStatus": {
"delivery": "OK"
}
},
"proposals": [
{
"status": "NOT_FOUND"
},
{
"status": "FOUND",
"routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"pickupStartSec": 38265,
"deliveryStartSec": 43549,
"routeCost": 201675,
"deltaCost": 10498
},
{
"status": "NOT_FOUND"
}
]
}
}
Given an Order and a set of desired time slots, computes, for each slot, a “proposal” identifying the best Route that the Order can be assigned to in that slot (asynchronous).
Because of resource saturation or other constraints it may happen that, for some slots, the Order cannot be assigned to any Route. In that case the computed set of proposals will include “empty” proposals.
Once computed, the “set of proposals” is temporarily stored allowing for proposals in the set to be reviewed and, possibly, for one of them to be selected and applied.
THROTTLING
Concurrency-limit (max 3 concurrent computations)
Quantity-limit (max 10 stored results)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals
REQUEST BODY
Property | Type | Description |
---|---|---|
order | OrderInput | Order for which we want to compute a set of proposals. The system will assign a UUID to the Order and return it in the proposalsSetProcessed notification message, in the order.id field.Note: the Order is only added to the plan when one of the computed proposals is applied. Note: timeWindows , timeWindowsExceptions and eligibility fields are ignored (see timeSlots below). |
timeSlots | list of TimeSlot | Alternative time-slots applied to the Order’s TimeWindow and Eligibility properties to compute possible assignments LIMITS: cannot contain more than 7 TimeSlots. LIMITS: timeSlot’s date cannot be today’s working date (unless today’s working date has zero Approved Routes). |
overrideLockedRoutes | boolean | Optional. Defaults to false. If set to false UI-defined locks are honored. If set to true UI-defined locks are ignored (i.e.: all Routes and Vehicles are valid candidates) |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification). Also used to identify the ProposalsSet object generated as a result of the computation. |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to proposalsSetProcessed |
data | ProposalsSetProcessed OR ErrorResponse |
Get ProposalsSet
curl -X GET https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY
GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
The above command returns JSON structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"requestStatus": "COMPLETED",
"expiryTs": 1423047900,
"order": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"name": "Order 6 - Proposal",
"eligibility": {
"type": "any"
},
"forceVehicleId": null,
"priority": 0,
"loads": {
"people": 2
},
"delivery": {
"location": {
"address": "2001 2nd Ave, Jasper, AL 35501, USA"
},
"timeWindows": [],
"notes": "Proposal order to be added via API",
"serviceTimeSec": 1800,
"tagsIn": [],
"tagsOut": [],
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"isService": false
},
"proposals": [
{
"status": "NOT_FOUND"
},
{
"status": "FOUND",
"data": {
"routes": {
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
"id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"revision": -1,
"date": "20151204",
"vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"driverId": null,
"steps": [
{
"type": "departure",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 0,
"startSec": 0,
"endSec": 28800,
"driveToNextSec": 2918,
"distanceToNextMt": 73402,
"stopIdx": 0,
"displayLabel": ""
},
{
"type": "pickup",
"orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 31718,
"startSec": 31718,
"endSec": 32318,
"driveToNextSec": 2917,
"distanceToNextMt": 73549,
"stopIdx": 1,
"displayLabel": ""
},
{
"type": "delivery",
"orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 35235,
"startSec": 35235,
"endSec": 36135,
"driveToNextSec": 48,
"distanceToNextMt": 334,
"stopIdx": 2,
"displayLabel": ""
},
{
"type": "delivery",
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 38265,
"startSec": 38265,
"endSec": 40065,
"driveToNextSec": 123,
"distanceToNextMt": 846,
"stopIdx": 3,
"displayLabel": ""
},
{
"type": "arrival",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 40188,
"startSec": 40188,
"endSec": 40188,
"driveToNextSec": 0,
"distanceToNextMt": 0,
"stopIdx": 4,
"displayLabel": ""
}
],
"trackingData": null
}
},
"orders": {
"fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"name": "Order 6 - Proposal",
"eligibility": {
"on": "20151204"
},
"forceVehicleId": null,
"priority": 0,
"loads": {
"people": 2
},
"delivery": {
"location": {
"address": "2001 2nd Ave, Jasper, AL 35501, USA"
},
"timeWindows": [
{
"startSec": 46800,
"endSec": 50400
}
],
"notes": "Proposal order to be added via API",
"serviceTimeSec": 1800,
"tagsIn": [],
"tagsOut": [],
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"isService": false
},
"e2524914-3611-433b-9209-3ee59ee3996e": {
"id": "e2524914-3611-433b-9209-3ee59ee3996e",
"name": "Order 6",
"eligibility": {
"type": "any",
"onDates": [
"20151203"
]
},
"forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"priority": 0,
"loads": {
"people": 400
},
"pickup": {
"depotId": null,
"location": {
"address": "1919 28th Ave S, Birmingham, AL 35209, United States",
"latLng": [
33480873,
-86788220
],
"status": "OK"
},
"timeWindows": [],
"notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
"serviceTimeSec": 600,
"tagsIn": [],
"tagsOut": [],
"customFields": {}
},
"delivery": null,
"isService": false
},
"deb5a845-40f8-42e0-963e-9646531894a4": {
"id": "deb5a845-40f8-42e0-963e-9646531894a4",
"name": "order2",
"eligibility": {
"type": "on",
"onDates": [
"20151205"
]
},
"forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"priority": 0,
"loads": {},
"pickup": null,
"delivery": {
"depotId": null,
"location": {
"address": "33.833605,-87.277556",
"latLng": [
33833604,
-87277556
],
"status": "OK"
},
"timeWindows": [],
"notes": "",
"serviceTimeSec": 900,
"tagsIn": [],
"tagsOut": [],
"customFields": {}
},
"isService": false
}
},
"vehicles": {
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
"id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"idx": 2,
"externalId": "Vehicle 2",
"tracked": true,
"color": "5500FF",
"settings": {
"20151203": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
},
"20151204": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
},
"20151205": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
}
}
}
},
"depots": {
"08f2f204-caf6-4b98-8767-9fd4e3b46307": {
"id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"name": "TEST",
"setupCost": -1,
"setupTimeSec": -1,
"location": {
"address": "320 20th St W, Jasper, AL 35501, USA",
"latLng": [
33831316,
-87278355
],
"status": "OK"
},
"color": "998800"
}
},
"drivers": {
"a3935987-4944-462f-b602-4a3a12beeeff": {
"id": "a3935987-4944-462f-b602-4a3a12beeeff",
"name": "Driver 1",
"email": "driver1@example.com"
}
}
},
"routeCost": 201675,
"deltaCost": 10498
},
{
"status": "NOT_FOUND"
}
]
}
Retrieve the set of proposals identified by proposalsSetId
(synchronous).
THROTTLING
Leaky bucket (size:20, refill: 1 per second)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId
RETURN VALUES (synchronous)
List ProposalsSets
curl -X GET https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals?key=AUTH_KEY
GET /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
The above command returns JSON structured like this:
[
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"requestStatus": "COMPLETED",
"expiryTs": 1423047900,
"order": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"name": "Order 6 - Proposal",
"eligibility": {
"type": "any"
},
"forceVehicleId": null,
"priority": 0,
"loads": {
"people": 2
},
"delivery": {
"location": {
"address": "2001 2nd Ave, Jasper, AL 35501, USA"
},
"timeWindows": [],
"notes": "Proposal order to be added via API",
"serviceTimeSec": 1800,
"tagsIn": [],
"tagsOut": [],
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"isService": false
},
"proposals": [
{
"status": "NOT_FOUND"
},
{
"status": "FOUND",
"data": {
"routes": {
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203": {
"id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"revision": -1,
"date": "20151204",
"vehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"driverId": null,
"steps": [
{
"type": "departure",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 0,
"startSec": 0,
"endSec": 28800,
"driveToNextSec": 2918,
"distanceToNextMt": 73402,
"stopIdx": 0,
"displayLabel": ""
},
{
"type": "pickup",
"orderId": "e2524914-3611-433b-9209-3ee59ee3996e",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 31718,
"startSec": 31718,
"endSec": 32318,
"driveToNextSec": 2917,
"distanceToNextMt": 73549,
"stopIdx": 1,
"displayLabel": ""
},
{
"type": "delivery",
"orderId": "deb5a845-40f8-42e0-963e-9646531894a4",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 35235,
"startSec": 35235,
"endSec": 36135,
"driveToNextSec": 48,
"distanceToNextMt": 334,
"stopIdx": 2,
"displayLabel": ""
},
{
"type": "delivery",
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 38265,
"startSec": 38265,
"endSec": 40065,
"driveToNextSec": 123,
"distanceToNextMt": 846,
"stopIdx": 3,
"displayLabel": ""
},
{
"type": "arrival",
"idleTimeSec": 0,
"perStopTimeSec": 0,
"arrivalSec": 40188,
"startSec": 40188,
"endSec": 40188,
"driveToNextSec": 0,
"distanceToNextMt": 0,
"stopIdx": 4,
"displayLabel": ""
}
],
"trackingData": null
}
},
"orders": {
"fb5e269b-9a16-4d44-abe5-a3f1c84acdb7": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"name": "Order 6 - Proposal",
"eligibility": {
"on": "20151204"
},
"forceVehicleId": null,
"priority": 0,
"loads": {
"people": 2
},
"delivery": {
"location": {
"address": "2001 2nd Ave, Jasper, AL 35501, USA"
},
"timeWindows": [
{
"startSec": 46800,
"endSec": 50400
}
],
"notes": "Proposal order to be added via API",
"serviceTimeSec": 1800,
"tagsIn": [],
"tagsOut": [],
"customFields": {
"my custom field": "custom field content",
"orderId": "abcd1234"
}
},
"isService": false
},
"e2524914-3611-433b-9209-3ee59ee3996e": {
"id": "e2524914-3611-433b-9209-3ee59ee3996e",
"name": "Order 6",
"eligibility": {
"type": "any",
"onDates": [
"20151203"
]
},
"forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"priority": 0,
"loads": {
"people": 400
},
"pickup": {
"depotId": null,
"location": {
"address": "1919 28th Ave S, Birmingham, AL 35209, United States",
"latLng": [
33480873,
-86788220
],
"status": "OK"
},
"timeWindows": [],
"notes": "Demonstrate the concept of force a vehicle, apply different eligibility type",
"serviceTimeSec": 600,
"tagsIn": [],
"tagsOut": [],
"customFields": {}
},
"delivery": null,
"isService": false
},
"deb5a845-40f8-42e0-963e-9646531894a4": {
"id": "deb5a845-40f8-42e0-963e-9646531894a4",
"name": "order2",
"eligibility": {
"type": "on",
"onDates": [
"20151205"
]
},
"forceVehicleId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"priority": 0,
"loads": {},
"pickup": null,
"delivery": {
"depotId": null,
"location": {
"address": "33.833605,-87.277556",
"latLng": [
33833604,
-87277556
],
"status": "OK"
},
"timeWindows": [],
"notes": "",
"serviceTimeSec": 900,
"tagsIn": [],
"tagsOut": [],
"customFields": {}
},
"isService": false
}
},
"vehicles": {
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7": {
"id": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7",
"idx": 2,
"externalId": "Vehicle 2",
"tracked": true,
"color": "5500FF",
"settings": {
"20151203": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
},
"20151204": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
},
"20151205": {
"available": true,
"notes": "",
"departureDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"arrivalDepotId": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"timeWindow": {
"startSec": 28800,
"endSec": 61200
},
"flexStartTime": true,
"perStopCost": 0,
"perStopTimeSec": 0,
"maxWorkingTimeSec": 0,
"maxDrivingTimeSec": 0,
"maxDistanceMt": 0,
"maxOrders": 0,
"breaks": [],
"loadCapacities": {
"people": 600
},
"regionIds": ["ddcbe348-5b4d-483d-9d6c-1b149120ca7e"],
"activationCost": 0,
"drivingTimeCost": 2000,
"idleTimeCost": 2000,
"serviceTimeCost": 2000,
"breakTimeCost": 2000,
"kmCost": 100,
"tags": [
"heavy"
],
"speedFactor": 100,
"minWorkingTimeSec": 0,
"minLoadCapacities": {}
}
}
}
},
"depots": {
"08f2f204-caf6-4b98-8767-9fd4e3b46307": {
"id": "08f2f204-caf6-4b98-8767-9fd4e3b46307",
"name": "TEST",
"setupCost": -1,
"setupTimeSec": -1,
"location": {
"address": "320 20th St W, Jasper, AL 35501, USA",
"latLng": [
33831316,
-87278355
],
"status": "OK"
},
"color": "998800"
}
},
"drivers": {
"a3935987-4944-462f-b602-4a3a12beeeff": {
"id": "a3935987-4944-462f-b602-4a3a12beeeff",
"name": "Driver 1",
"email": "driver1@example.com"
}
}
},
"routeCost": 201675,
"deltaCost": 10498
},
{
"status": "NOT_FOUND"
}
]
}
]
Retrieve all sets of proposals for the specified territory (synchronous).
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals
RETURN VALUES (synchronous)
List of ProposalsSet
Delete ProposalsSet
curl -X DELETE https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY
DELETE /api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
The above command returns JSON structured like this:
{}
Deletes the set of proposals identified by proposalsSetId
.
Note: If the computation of the specified set is still in progress it is cancelled.
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
DELETE https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId
RETURN VALUES (synchronous)
Empty object
Apply Proposal
curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0?key=AUTH_KEY
POST /territories/429defc8-5b05-4c3e-920d-0bb911a61345/experimental/proposals/f59d7e47-d67b-41a6-9cd4-fca9d481dec0 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"proposalsIndexes": [
0,1
],
"ignoreRevision": true,
"costPercentThreshold": 10
}
The above command returns JSON structured like this:
{
"requestId": "16e00aeb-7c2b-46d2-b0c8-8b7ccc9c7060"
}
And triggers an ProposalApplied Notification (POSTed to the callback URL) structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "proposalApplied",
"data": {
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"proposalIndexApplied": 1
}
}
Accept the requested proposal from the given set of proposals, adding the Order to the plan and assigning it to the Route identified by the selected proposal (asynchronous).
The default behavior appies the proposal only if the revision number of the Route identified by the proposal has not changed since the proposals computation. It’s possible to enable a more “smart” behavior that will try to insert anyway the proposal within the current route (i.e. the one with the revision number changed) in the same time-slot chosen for the original route, and performs some validation to see if it still fit.
If the selected proposal is not applicable the message within the response will contain a list of the proposals that were computed but not chosen by the user and that are still applicable to the updated Route, if any.
Note: If two or more proposals are passed in input, the first one that is acceptable will be applied.
Note: Successfully applying a proposal automatically removes its owning ProposalsSet, freeing up room for computing a new set of proposals
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
PUT https://wwrm.workwave.com/api/v1/territories/:territoryId/experimental/proposals/:proposalsSetId
REQUEST BODY
Property | Type | Description |
---|---|---|
proposalsIndexes | list of int | List of zero-based indexes: each index i corresponds to i-th proposal to be applied within the set of proposals. If multiple indexes are passed, the first compatible result in the list is applied. |
ignoreRevision | boolean | Optional. Default to false. If set to false the proposal will be applied only if the revision of the Route identified by the proposal has not changed since the proposals computation. If set to true and the revision of the Route in the proposal changed, the proposal will be applied anyway within the identified time-slot. Then some validation will be performed to check if the route obtained is valid (no violations added and total cost under the given threshold). If the route is valid, the new route (including the proposal order) overwrites the old one, otherwise the request will fail. |
costPercentThreshold | int | Optional. The scheduling of the proposal order within the route in case of changed revision can increase the route cost from the initial proposal. This value sets a maximum allowed amount of cost increase, in percentage. E.g. if costPercentThreshold is set to 10, the new route containing the proposal order will not be accepted in case its cost is more than 10% higher respect to the cost of the original proposal route computed.Note: Used only if ignoreRevision is set to true. |
RETURN VALUES (synchronous)
Property | Type | Description |
---|---|---|
requestId | String | Request ID assigned to the asynchronous request (reported in the asynchronous notification). |
RETURN VALUES (asynchronous notification)
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to proposalApplied |
data | ProposalApplied OR ErrorResponse |
GPS Tracking API
List GPS Devices
curl https://wwrm.workwave.com/api/v1/gps/devices?key=AUTH_KEY
GET /api/v1/gps/devices HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"devices": {
"40519": {
"id": "40519",
"label": "Green Van - SBA 1234A" ,
"category": "PHYSICAL"
},
"41267": {
"id": "41267",
"label": "Red Van - SBA 7231B" ,
"category": "PHYSICAL"
},
"42676": {
"id": "42676",
"label": "Yellow Van - SBA 6183A" ,
"category": "PHYSICAL"
},
"57290": {
"id": "57290",
"label": "Alice's Phone",
"category": "MOBILE"
},
"57291": {
"id": "57291",
"label": "Bob's Phone",
"category": "MOBILE"
}
}
}
List all GPS devices as provisioned on the connected WorkWave GPS service (synchronous).
A GPS device can be either PHYSICAL
(e.g.: a GPS unit installed in a vehicle) or MOBILE
(e.g.: a smartphone where the WorkWave Route Manger App is installed).
THROTTLING
Rate-limit (1 call every 10 secs)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/gps/devices
RETURN VALUES
Property | Type | Description |
---|---|---|
devices | map[String]GpsDevice | A map where the key is the GPS deviceId and the value is the associated GpsDevice object |
List Current GPS Info
curl https://wwrm.workwave.com/api/v1/gps/devices/current?key=AUTH_KEY
GET /api/v1/gps/devices/current HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"currentInfos": {
"40519": {
"id": "40519",
"latLng": [
33817872,
-87266893
],
"ts": 1449150077,
"heading": 60,
"speedMs": 7
},
"41267": {
"id": "41267",
"latLng": [
33480873,
-86788220
],
"ts": 1449142877,
"heading": 101,
"speedMs": 9
},
"42676": {
"id": "42676",
"latLng": [
33480873,
-86788220
],
"ts": 1449154517,
"heading": 242,
"speedMs": 0
},
"57290": {
"id": "57290",
"latLng": [
33833604,
-87277556
],
"ts": 1449156217,
"heading": 342,
"speedMs": 20
},
"57291": {
"id": "57291",
"latLng": [
33836824,
-87266029
],
"ts": 1449155557,
"heading": 164,
"speedMs": 0
}
}
}
Return last-known/most-recent information about all provisioned GPS devices. This includes timestamp, position, heading and speed (synchronous).
THROTTLING
Rate-limit (1 call every 10 secs)
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/gps/devices/current
RETURN VALUES
Property | Type | Description |
---|---|---|
currentInfos | map[String]GpsSample | A map where the key is the GPS deviceId and the value is the associated GpsSample object |
WebHook API
List WebHook Subscription
curl https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY
GET /api/v1/webhooksubscriptions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
The above command returns JSON structured like this:
{
"subscriptions": {
"0ed46547-a79c-48b4-b108-4ccd98d44d8b": {
"id": "0ed46547-a79c-48b4-b108-4ccd98d44d8b",
"events": [
"ORDER_UPDATED"
],
"territoryIds": [
"0c8bcd10-225a-4acd-a47f-12d1e3077891"
],
"url": "https://my.server.com/webhook-test-1",
"hmacSecret": "abcd123",
"enabled": "true",
"queueBy": "SUBSCRIPTION",
"headers": {
"testHeader": "testHeaderBody"
},
"createTs": "2022-02-17T09:29:27.6167653Z"
},
"2e901af2-8d1f-4bf8-825a-6a57fe0b5372": {
"id": "2e901af2-8d1f-4bf8-825a-6a57fe0b5372",
"events": [],
"territoryIds": [],
"enabled": false,
"queueBy": "TERRITORY",
"url": "https://my.server.com/webhook-test-2",
"headers": {},
"createTs": "2022-02-16T13:27:26.0062027Z"
}
}
}
Returns all the WebHook Subscriptions active for the invoking account (synchronous).
HTTP REQUEST
GET https://wwrm.workwave.com/api/v1/webhooksubscriptions
THROTTLING
Leaky bucket (size:1, refill: 1 per seconds)
RETURN VALUES
Property | Type | Description |
---|---|---|
subscriptions | map[UUID]WebHookSubscription | A map where the key is the WebHook Subscription ID and the value is the WebHookSubscription correlated. It contains all the WebHook Subscription active for the invoking account. |
Add WebHook Subscription
curl -H "Content-Type: application/json" -X POST -d 'insert request body below' https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY
POST /api/v1/webhooksubscriptions HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"subscriptions": [
{
"events": [
"ORDER_UPDATED"
],
"territoryIds": [
"0c8bcd10-225a-4acd-a47f-12d1e3077891"
],
"url": "https://my.server.com/webhook-test-1",
"hmacSecret": "abcd123",
"enabled": true,
"queueBy": "SUBSCRIPTION",
"headers": {
"testHeader": "testHeaderBody"
}
},
{
"events": [],
"territoryIds": [],
"url": "https://my.server.com/webhook-test-2",
"enabled": false,
"queueBy": "TERRITORY",
"headers": {}
}
]
}
The above command returns JSON structured like this:
{
"subscriptions": {
"0ed46547-a79c-48b4-b108-4ccd98d44d8b": {
"id": "0ed46547-a79c-48b4-b108-4ccd98d44d8b",
"events": [
"ORDER_UPDATED"
],
"territoryIds": [
"0c8bcd10-225a-4acd-a47f-12d1e3077891"
],
"url": "https://my.server.com/webhook-test-1",
"enabled": true,
"queueBy": "SUBSCRIPTION",
"hmacSecret": "abcd123",
"headers": {
"testHeader": "testHeaderBody"
},
"createTs": "2022-02-17T09:29:27.6167653Z"
},
"2e901af2-8d1f-4bf8-825a-6a57fe0b5372": {
"id": "2e901af2-8d1f-4bf8-825a-6a57fe0b5372",
"events": [],
"territoryIds": [],
"url": "https://my.server.com/webhook-test-2",
"enabled": false,
"queueBy": "TERRITORY",
"headers": {},
"createTs": "2022-02-16T13:27:26.0062027Z"
}
}
}
Subscribe to a list of TerritoryIds and events with a WebHook URL (synchronous).
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
POST https://wwrm.workwave.com/api/v1/webhooksubscriptions
REQUEST BODY
Property | Type | Description |
---|---|---|
subscriptions | List of WebHookSubscriptionInput | The list of WebHookSubscription requested |
RETURN VALUES
Property | Type | Description |
---|---|---|
subscriptions | Map [UUID]WebHookSubscription | A map where the subscription is the WebHook Subscription ID and teh value is the WebHookSubscription created. |
Update WebHook Subscription
curl -H "Content-Type: application/json" -X PUT -d 'insert request body below' https://wwrm.workwave.com/api/v1/webhooksubscriptions/2e901af2-8d1f-4bf8-825a-6a57fe0b5372?key=AUTH_KEY
PUT /api/v1/webhooksubscriptions/2e901af2-8d1f-4bf8-825a-6a57fe0b5372 HTTP/1.0
Accept: application/json
X-WorkWave-Key: YOUR API KEY
Host: wwrm.workwave.com
Content-Type: application/json
{
"enabled": true
}
The above command returns JSON structured like this:
{
"enabled": true
}
Enable or disable an existing WebHook Subscription.
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
PUT https://wwrm.workwave.com/api/v1/webhooksubscriptions/:subscriptionId
REQUEST BODY
Property | Type | Description |
---|---|---|
enabled | boolean | The desired state for the Subscription. |
RETURN VALUES
Property | Type | Description |
---|---|---|
enabled | boolean | The set state for the Subscription. |
Delete WebHook Subscription
curl https://wwrm.workwave.com/api/v1/webhooksubscriptions?key=AUTH_KEY&ids='comma separated ids'
DELETE /api/v1/webhooksubscriptions[?ids=<comma_separated_list>] HTTP/1.0
The above command returns a response like this:
true
And in case the test fails:
{
"errorCode": 100,
"errorMessage": "ids list cannot be empty"
}
Delete the WebHook Subscriptions (synchronous).
THROTTLING
Leaky bucket (size:10, refill: 1 per second)
HTTP REQUEST
DELETE https://wwrm.workwave.com/api/v1/webhooksubscriptions[?ids=<comma_separated_list>]
QUERYSTRING PARAMETERS
Property | Type | Description |
---|---|---|
ids | comma-separated list of String | Ids of Subscriptions to be deleted. Note: if only the * character is sent as ids, all the subscription for the account will be deleted.LIMITS: due to querystring length limitations the number of IDs that can be safely specified should not exceed 200. |
If the request is successfully completed, the value response will contains the true
value in the body as plain text.
Asynchronous Notifications
Mechanics
Async notifications are POSTed to the configured Callback URL under the following circumstances:
- to notify the completion of an asynchronous API request
- to notify that some Orders changed as the result of either an API request or a manual request performed via the Web Application
- to notify that Routes for a given date have been marked as “Approved”
When one of the above events happens, an HTTP(S) POST request is sent from one the WorkWave Route Manager servers to the Callback URL.
Different notifications carry different information encoded in JSON format in the request body. The format of each body type is outlined in the following Chapters.
The remote server is expected to accept the TCP connection within 5 seconds and return an HTTP 200 OK code within 15 seconds.
Failing that, the Callback URL is invoked again up to 5 times according to the following retry strategy:
- 1st invocation: immediately
- subsequent invocations: after
(#retries * 20)
seconds
It is therefore strongly advised not to perform any time-consuming processing logic as part of the thread that receives the notification request, but to delegate such actions to other threads so that the receiving thread can immediately reply with a 200 OK response.
OrdersChanged Notification
Adding new Orders triggers a notification structured like this:
{
"requestId": "509900a5-392e-4d34-bcfe-90cc6bf3ad47",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "ordersChanged",
"data": {
"created": [
{
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"geocodeStatus": {
"delivery": "OK"
}
},
{
"id": "89009ba2-285f-47a1-8b91-5524d8f31b16",
"geocodeStatus": {
"delivery": "LOW_ACCURACY"
}
},
{
"id": "6a0c1374-e07c-410d-98d2-dd7be1f02ffa",
"geocodeStatus": {
"delivery": "NOT_FOUND"
}
},
{
"id": "3d499ad0-14f6-4a38-acd8-05b8269dec78",
"geocodeStatus": {
"delivery": "POSTCODE_ISSUE"
}
},
{
"id": "a5682ad9-97e8-4719-9bb6-eecfcfb8606b",
"geocodeStatus": {
"delivery": "OK"
}
}
],
"updated": [],
"deleted": []
}
}
Updating or replacing an existing Order triggers a notification structured like this:
{
"requestId": "cdecbe3a-4115-4240-8d44-0cfa2fc14fb6",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "ordersChanged",
"data": {
"created": [],
"updated": [
{
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"geocodeStatus": {
"delivery": "OK"
}
}
],
"deleted": []
}
}
Deleting Orders triggers a notification structured like this:
{
"requestId": "9c66f107-320f-4ae5-85f6-3dddaa7c8c8e",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "ordersChanged",
"data": {
"created": [],
"updated": [],
"deleted": [
"fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"a5682ad9-97e8-4719-9bb6-eecfcfb8606b"
]
}
}
Notifies that some Orders’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Orders API or of a manual operation performed via the Web Application.
In general, any operation that changes Orders’ data (create/update/delete) triggers an ordersChanged
notification.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action
that was initiated by itself (by checking the requestId
) and if not, issue a Get Orders request to fetch the details of the updated Order(s).
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to ordersChanged |
data | OrdersChanged OR ErrorResponse | Details about the outcome of the change event |
VehiclesChanged Notification
Adding a new Vehicle (from the UI) triggers a notification structured like this:
{
"requestId": null,
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "vehiclesChanged",
"data": {
"created": [
"875cceab-0952-4101-9db3-e524dbec9a75"
],
"updated": [],
"deleted": []
}
}
Updating an existing Vehicle triggers a notification structured like this:
{
"requestId": "302f2060-c132-4079-8565-9f543ea581ea",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "vehiclesChanged",
"data": {
"created": [],
"updated": [
"31656f79-cba7-4bcf-a959-e3fe3f7ca2a7"
],
"deleted": []
}
}
Deleting a Vehicle (from the UI) triggers a notification structured like this:
{
"requestId": null,
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "vehiclesChanged",
"data": {
"created": [],
"updated": [],
"deleted": [
"0d8855e6-28a0-4e89-9c67-b44c66c39ba6"
]
}
}
Notifies that some Vehicles’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Vehicles API or of a manual operation performed via the Web Application.
In general, any operation that changes Vehicles’ data (create/update/delete) triggers a vehiclesChanged
notification.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action
that was initiated by itself (by checking the requestId
) and if not, issue a List Vehicles or a Get Vehicle Settings request to fetch the details of the updated Vehicle(s).
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to vehiclesChanged |
data | VehiclesChanged OR ErrorResponse | Details about the outcome of the change event |
DriversChanged Notification
Adding a new Driver triggers a notification structured like this:
{
"requestId": "88b79f3b-28bf-4bd6-82ae-9c523f3cc20b",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "driversChanged",
"data": {
"created": [
"0129724f-b80d-4011-ab91-3e4ae2f62896"
],
"updated": [],
"deleted": []
}
}
Updating an existing Driver triggers a notification structured like this:
{
"requestId": "9ca2501f-19f1-42b0-b17c-3ebe585776c6",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "driversChanged",
"data": {
"created": [],
"updated": [
"a3935987-4944-462f-b602-4a3a12beeeff"
],
"deleted": []
}
}
Deleting a Driver triggers a notification structured like this:
{
"requestId": "aac2fe79-5cc9-485a-9a24-b48d3d03db49",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "driversChanged",
"data": {
"created": [],
"updated": [],
"deleted": [
"a08213e6-673f-4efc-955e-2bf587813162"
]
}
}
Notifies that some Drivers’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Drivers API or of a manual operation performed via the Web Application.
In general, any operation that changes Drivers’ data (create/update/delete) triggers a driversChanged
notification.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action
that was initiated by itself (by checking the requestId
) and if not, issue a List Drivers request to fetch the details of the updated Drivers.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to driversChanged |
data | DriversChanged OR ErrorResponse | Details about the outcome of the change event |
VehicleDriverAssignmentsChanged Notification
Replacing Vehicle-Drivers Assignments triggers a notification structured like this:
{
"requestId": "c3f7257a-3c5d-4870-bddc-e8845da1a227",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "vehicleDriverAssignmentsChanged",
"data": {}
}
Notifies that some Vehicle-Driver assignments have changed.
This can be the result of an asynchronous API request such as the ones described at Vehicle-Driver Assignments API or of a manual operation performed via the Web Application.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action
that was initiated by itself (by checking the requestId
) and if not, issue a Get Driver Assignments request to fetch the details of the updated assignments.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to vehicleDriverAssignmentsChanged |
data | empty object OR ErrorResponse |
ExecutionEventsProcessed Notification
Sending Execution Events triggers a notification structured like this:
{
"requestId": "a6f01d6b-a085-4812-8784-48d26d888809",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "executionEventsProcessed",
"data": {
"processed": [
"OK",
"OK",
"ERROR_VEHICLE_NOT_TRACKED",
"OK_WARN_LATLNG_OUT_OF_BOUNDS",
"OK"
]
}
}
Sending Execution Events while a WebApp-initiated Editing Transaction is in progress triggers a notification structured like this:
{
"requestId": "303dd2b5-22c4-4fe9-9586-a6b168d96658",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "executionEventsProcessed",
"data": {
"processed": [
"POSTPONED",
"POSTPONED",
"POSTPONED"
]
}
}
Notifies that an API-initiated Send Execution Events request completed.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to executionEventsProcessed |
data | ExecutionEventsProcessed OR ErrorResponse | Details about the outcome of the update event |
ApprovedRoutesChanged Notification
Approving Routes and/or revoking Routes approval triggers a notification structured like this:
{
"requestId": "94accf16-dab4-4a6d-85b1-eda4bff10842",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "approvedRoutesChanged",
"data": {
"approved": ["20151204", "20151205"],
"revoked": ["20151206"]
}
}
Notifies changes to dates where Routes have been either marked as approved (i.e.: ready to be dispatched and visible to mobile apps) or have been revoked approval (i.e.: not ready to be dispatched, no more visible to mobile apps).
This is the result of either API-initiated Approve Routes or Revoke Routes requests or a manual operation performed via the Web Application (via the “Approve and Dispatch” button).
An application interested in this type of notification would, upon receiving it, typically issue a List Approved Routes request to retrieve details about the approved Routes.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to approvedRoutesChanged |
data | ApprovedRoutesChanged OR ErrorResponse | Details about the outcome of the update event |
SchedulingCompleted Notification
Building Routes triggers a notification structured like this:
{
"requestId": "758aa6e2-f450-4f2e-9559-b928e39fb5f9",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {}
}
Fitting-In Unassigned Orders triggers a notification structured like this:
{
"requestId": "13d8ddf5-7fbc-49e5-a2b3-cb4d10b80827",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderIds": [
"603a348f-7fcc-4bdc-8f4a-ec10a68547e0"
]
}
}
Unassigning Orders triggers a notification structured like this:
{
"requestId": "1bf2f905-522f-42ab-bc06-d2bfb5dd4f06",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderIds": [
"603a348f-7fcc-4bdc-8f4a-ec10a68547e0"
]
}
}
Assigning OrderSteps triggers a notification structured like this:
{
"requestId": "ebc076b0-18ba-40d6-963a-288d0cc1e33f",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderSteps": [
{
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"type": "delivery"
}
]
}
}
Notifies that an API-initiated scheduling request completed.
This is the result of the asynchronous API requests described at Scheduling API.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to schedulingCompleted |
data | SchedulingCompleted OR ErrorResponse | Details about the outcome of the update event |
ProposalsSetProcessed Notification
Compute ProposalsSet triggers a notification structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "proposalsSetProcessed",
"data": {
"order": {
"id": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"geocodeStatus": {
"delivery": "OK"
}
},
"proposals": [
{
"status": "NOT_FOUND"
},
{
"status": "FOUND",
"routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"pickupStartSec": 38265,
"deliveryStartSec": 43549,
"routeCost": 201675,
"deltaCost": 10498
},
{
"status": "NOT_FOUND"
}
]
}
}
Notifies that of a set of proposals has been computed and stored for review and proposal application
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request, also doubles as the ID of the stored ProposalsSet |
territoryId | UUID | Territory ID |
event | String | Set to proposalsSetProcessed |
data | ProposalsSetProcessed OR ErrorResponse | Details about the outcome of the processed event |
ProposalApplied Notification
Apply Proposal triggers a notification structured like this:
{
"requestId": "f59d7e47-d67b-41a6-9cd4-fca9d481dec0",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "schedulingCompleted",
"data": {
"orderId": "fb5e269b-9a16-4d44-abe5-a3f1c84acdb7",
"routeId": "31656f79-cba7-4bcf-a959-e3fe3f7ca2a7-20151203",
"proposalIndexApplied": 1
}
}
Notifies the application of a proposal, resulting in the addition of the Order to the plan and its assignment to the Route identified by the selected proposal.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request |
territoryId | UUID | Territory ID |
event | String | Set to proposalApplied |
data | ProposalApplied OR ErrorResponse | Details about the outcome of the processed event |
RegionsChanged Notification
Adding a new Region triggers a notification structured like this:
{
"requestId": "7d69fd36-3841-4ec6-bdc4-775f5e550918",
"territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
"event": "regionsChanged",
"data": {
"created": [
"6543c0c1-d55e-46e1-ae3c-65d26239351c"
],
"updated": [],
"deleted": []
}
}
Updating an existing Region triggers a notification structured like this:
{
"requestId": "f97f7a00-8751-4bd7-920e-c5a7cdca2958",
"territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
"event": "regionsChanged",
"data": {
"created": [],
"updated": [
"584cc8bf-3fee-41a2-81f1-8ab1d6b15269"
],
"deleted": []
}
}
Deleting a Region triggers a notification structured like this:
{
"requestId": "72cbfae8-d75e-444a-8b98-6a4da3e91452",
"territoryId": "0c8bcd10-225a-4acd-a47f-12d1e3077891",
"event": "regionsChanged",
"data": {
"created": [],
"updated": [],
"deleted": [
"539d3609-58bc-4445-b068-69cb8d977ef9"
]
}
}
Notifies that some Regions’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Regions API or a manual operation performed via the Web Application.
In general, any operation that change Regions’ data (create/update/delete) triggers a regionsChanged
notification.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action that was initiated by itself (by checking the requestId
) and, if not, issue a List Regions request to fetch the details of the updated Regions.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String OR null |
Request ID associated to the originating asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to regionsChanged |
data | RegionsChanged OR ErrorResponse | Details about the outcome of the change event |
DepotsChanged Notification
Adding a new Depot triggers a notification structured like this:
{
"requestId": "88b79f3b-28bf-4bd6-82ae-9c523f3cc20b",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "depotsChanged",
"data": {
"created": [
"0129724f-b80d-4011-ab91-3e4ae2f62896"
],
"updated": [],
"deleted": []
}
}
Updating an existing Depot triggers a notification structured like this:
{
"requestId": "9ca2501f-19f1-42b0-b17c-3ebe585776c6",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "depotsChanged",
"data": {
"created": [],
"updated": [
"a3935987-4944-462f-b602-4a3a12beeeff"
],
"deleted": []
}
}
Deleting a Depot triggers a notification structured like this:
{
"requestId": "aac2fe79-5cc9-485a-9a24-b48d3d03db49",
"territoryId": "429defc8-5b05-4c3e-920d-0bb911a61345",
"event": "depotsChanged",
"data": {
"created": [],
"updated": [],
"deleted": [
"a08213e6-673f-4efc-955e-2bf587813162"
]
}
}
Notifies that some Depots’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Depots API or of a manual operation performed via the Web Application.
In general, any operation that changes Depots’ data (create/update/delete) triggers a depotsChanged
notification.
An application interested in this type of notification would, upon receiving it, typically check whether the notification is about an action
that was initiated by itself (by checking the requestId
) and if not, issue a List Depots request to fetch the details of the updated Depots.
REQUEST BODY
Property | Type | Description |
---|---|---|
requestId | String | Request ID associated to the asynchronous request, or null if the originating request is a manual change (performed from the UI) |
territoryId | UUID | Territory ID |
event | String | Set to depotsChanged |
data | DepotsChanged OR ErrorResponse | Details about the outcome of the processed event |
WebHook Notifications
Mechanics
WebHook notifications are POSTed to the WebHook URL set in the WebHook Subscription when the event the subscription refers to happens in the Plan, if the subscription is enabled. A single subscription can refer to multiple events.
Different notifications carry different information encoded in JSON format in the request body. The format of each body type is outlined in the following Chapters.
The remote server is expected to accept the TCP connection within 10 seconds and return an HTTP 200 OK code within 10 seconds.
Failing that, the invokation is repeated according to the following retry strategy:
- every (10 * 2^#retries) sec (max 120 sec)
- after a few hours the request is considered expired and removed.
If you need to do any processing that could take more than 10 seconds in response to a webhook, it’s strongly advised to queue such actions for later processing in your system upon receiving the webhook and immediatedly reply with a 200 OK response.
Note: If the remote server replies with an HTTP code of 404 error, the subscription will be disabled immediately.
If the remote server replies with an HTTP code that does not belong to the 2xx success code class and it’s not 404 error for more than a few days, the subscription will be disabled.
When disabled, a subscription is still present, but will not send any notification for the events it refers to. The state can be modified with the Update WebHook Subscription invokation.
Orders Notification
Changes to an order triggers a notification structured like this:
{
"apiRequestId": null,
"territoryId": "cc52648e-0221-409b-8a63-b325331b56eb",
"timeZoneCode": "America/New_York",
"eventType": "ORDER_ADDED",
"orders": {
"571bcb74-8905-4c77-9ff9-3517958f65b0": {
"id": "571bcb74-8905-4c77-9ff9-3517958f65b0",
"name": "New Order 1",
"eligibility": {
"type": "any"
},
"forceVehicleId": null,
"priority": 0,
"loads": {},
"pickup": {
"depotId": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
"location": null,
"timeWindows": [],
"timeWindowExceptions": {},
"notes": "",
"phone": null,
"email": null,
"serviceTimeSec": 0,
"tagsIn": [],
"tagsOut": [],
"customFields": {},
"barcodes": []
},
"delivery": {
"depotId": null,
"location": {
"address": "189 Frelinghuysen Ave, Newark, NJ 07114, USA",
"latLng": [
40715249,
-74188244
],
"status": "OK",
"geoAddress": "189 Frelinghuysen Ave, Newark, NJ 07114, USA"
},
"timeWindows": [],
"timeWindowExceptions": {},
"notes": "",
"phone": null,
"email": null,
"serviceTimeSec": 0,
"tagsIn": [],
"tagsOut": [],
"customFields": {},
"barcodes": []
},
"isService": false,
"integrationData": null
}
},
"depots": {
"0363f92b-f67a-4f71-8e2a-e6ebd7f54633": {
"id": "0363f92b-f67a-4f71-8e2a-e6ebd7f54633",
"name": "Depot 1",
"setupCost": -1,
"setupTimeSec": -1,
"location": {
"address": "27 Scotland Rd, Elizabeth, NJ 07208, USA",
"latLng": [
40679643,
-74217459
],
"status": "OK",
"geoAddress": "27 Scotland Road, Elizabeth, NJ 07208, USA"
},
"color": null
}
}
}
Notifies that some Orders’ data has changed.
This can be the result of an asynchronous API request such as the ones described at Orders API or of a manual operation performed via the Web Application.
In general, any operation that changes Orders’ data (create/update/delete) triggers a WebHook notification that contains the new Order information.
RETURN VALUES
Property | Type | Description |
---|---|---|
apiRequestId | String OR < |