Skip to main content
API docs by Redocly

Spoke API (v1)

This is the documentation of the Spoke Public API HTTP endpoints. The Spoke Public API is a way for you to interact with Spoke products programmatically.

Introduction

The API has a set of HTTP methods to operate on Spoke resources for a specific team.

Currently, Spoke offers no programming SDKs for interacting with the Public API, but you can implement your own interface by calling the methods documented on this page.

v1 Migration Guide

If migrating from version 0.2b to v1, please note the following changes.

General

  1. Only api.spoke.com should be used for the v1 API.
  2. Webhooks requests will now only contain the spoke-signature header.

Stops

Removals:

Operation 0.2b Property v1 Property Notes
WRITE stop.driver stop.allowedDrivers Drivers should now be provided as an array of DriverIds.
READ stop.driverIdentifier stop.allowedDrivers Drivers will now be returned as an array of DriverIds.
READ stop.allowedDriverIdentifiers stop.allowedDrivers Drivers will now be returned as an array of DriverIds.
READ stop.etaNullReason stop.eta.status eta now has a status property with the same information.
READ stop.timeAtStopInfoNullReason stop.timeAtStopInfo.status timeAtStopInfo now has a status property with the same information.
READ/WRITE stop.circuitClientId stop.clientId When creating or reading stops, circuitClientId will now be clientId
READ stop.deliveryInfo.arrivedAt timeAtStopInfo.value.arrivedAt This property is only available when timeAtStopInfo.status === 'available'

Changes:

  1. READ: stop.eta is now an object containing both the eta value, and additional metadata about the value.
  2. READ: stop.timeAtStopInfo structure has changed so that the original properties are now under timeAtStopInfo.value.*, and an additional field timeAtStopInfo.status has been added to indicate why the info is not set.

Plans

Changes:

  1. Previously we would allow Drivers to be added even if their Depot did not match the plan's Depot. This is no longer allowed. Non-matching Drivers must now have their Depot changed to match the target Plan, or vice versa.
  2. Driver objects are no longer returned as part of Plan endpoint responses. Instead, DriverIds are returned and the associated drivers must be fetched separately (if needed).

Using the API

This section describes how the Spoke API should be used, if you wish to see example implementations take a look at the API Usage Examples page.

Address

The base API address for this version of the API to be used before every endpoint listed here is: https://api.spoke.com/public/v1

Notice the https:// prefix, Spoke API will not accept plain HTTP requests.

Authentication

To use Spoke Public API endpoints you will first need to generate an API key for authenticating with our servers.

To do this you need to go to your Spoke Dispatch settings page > Integrations > API, and generate a new key there.

Once you have the API key you can use it in the Authorization header either using the Basic scheme, or as a Bearer token.

Basic Auth

Basic Authentication is the primary authentication scheme used by Spoke's API.

Basic authentication typically uses a base64 encoded username:password pair, but since we only require an API key we instead structure the payload as [yourApiKey]:[empty]. This value is then base64 encoded as usual.

Example with curl:

curl "https://api.spoke.com/public/v1/plans" -u yourApiKey:

If you did everything correctly you should see a list of your team's plans in response to this request.

The -u flag adds a header to the request in the following format:

Authorization: Basic eW91ckFwaUtleToK

Note that curl automatically base64 encoded the data. Other clients will do the same e.g. if using Postman you would configure the request's Authorization option instead of adding a header directly.

Bearer Token

Alternatively you can pass the API key as a Bearer token without any special encoding. i.e. Authorization: Bearer [yourApiKey].

Example with curl:

curl "https://api.spoke.com/public/v1/plans" -H "Authorization: Bearer yourApiKey"

On resource types

Every response from the Spoke Public API will be as JSON Objects, and every request that has a body also needs to be in that type, and the header Content-type: application/json needs to present, so the server knows that the body you are sending is valid JSON. Spoke will reject requests without that header, so be sure to use it.

On resource IDs

Every resource in the Spoke Public API has a unique ID. This ID is generated by Spoke and is unique for every resource per collection.

Every resource representation returned by the API will show the ID in the following format:

{
  "id": "collectionName/resourceId"
}

And if the resource is on a sub-collection, it will be in the following format:

{
  "id": "collectionName/resourceId/subcollectionName/subResourceId"
}

For example, a stop with ID stop1 under a plan with ID plan1 will have the following representation on its serialized ID field:

{
  "id": "plans/plan1/stops/stop1"
}

This means that if you wish to directly retrieve this stop by using a GET endpoint you can simply use this ID as follows:

curl "https://api.spoke.com/public/v1/`serializedId`" -u yourApiKey:

For the example above this would be:

curl "https://api.spoke.com/public/v1/plans/plan1/stops/stop1" -u yourApiKey:

On List endpoints

When using list endpoints, you have the ability to combine various query options to locate the desired results. Some endpoints even offer specific filter options to aid in this search.

All the list endpoints employ pagination. This means that a single request might only return a part of the entire set of resources you're aiming to retrieve. To move through the subsequent pages, the Spoke API provides a nextPageToken field in the response of every list endpoint query.

It's crucial to understand that when a nextPageToken is returned, it indicates that more data is available. For every subsequent request, this token should be added as the pageToken query parameter. And, importantly, all the original query parameters used in the first request must also be included.

Here's a step-by-step example to elucidate this:

  1. Suppose you initiate a request to list your plans:
curl "https://api.spoke.com/public/v1/plans?filter.startsGte=2023-05-01" -u yourApiKey:
  1. The Spoke API might return a response like:
{
  // other attributes
  "nextPageToken": "I53Jr5Eu2qK9omh0iA8q"
}
  1. To retrieve the next page of data, use the returned nextPageToken as the pageToken query parameter, and ensure all initial query parameters remain the same:
curl "https://api.spoke.com/public/v1/plans?filter.startsGte=2023-05-01&pageToken=I53Jr5Eu2qK9omh0iA8q" -u yourApiKey:
  1. Repeat step 3 for all subsequent pages, updating the pageToken parameter with the latest nextPageToken value returned until nextPageToken is null in the response.

Spoke also accepts limiting the maximum number of results per page by using the maxPageSize query parameter, but notice that each individual endpoint has a maximum value you can set this to.

On Update endpoints (HTTP PATCH verb)

Update methods differ from the other methods in the API in the sense that missing values in the JSON representation will not act upon the representation of the resource.

Explaining this by example: Suppose you have a Plan with the ID plan1 in your plans' collection, and you wanted to merely update its title to My API Plan without changing other information, such as assigned drivers or the start date. To do this you would issue the following request:

curl -X PATCH http://localhost:5005/public/v1/plans/plan1 -H 'Content-type: application/json' -d '{"title": "My API Plan"}' -u yourApiKey:

Notice how we don't pass any other information in the JSON, only the title. This ensures that the PATCH request will only operate on the provided parameters and keep the other parameters as-is.

It is important to also notice that when updating an array the whole array will be replaced, Spoke API does not support partial updates on arrays.

On Rate-Limiting

All the endpoints in the Spoke Public API are rate-limited, which means we will reject requests that come in too fast.

To know if your request was rate-limited, check if the response has the HTTP status code 429.

Each endpoint has a different rate limit, and Spoke can change this rate limit at any moment.

The rate limits are as follows:

  • Rate Limits for Write Endpoints: All write endpoints have a limit of 5 requests per second, which includes Creation (POST), Update (PATCH), and Deletion (DELETE) operations for all models.
    • An exception to this rule is the Driver Creation endpoint, which is limited to 1 request per second. Thus, we recommend using the Batch Import Drivers when adding multiple drivers.
  • Rate Limits for Read Endpoints: All read endpoints, including list endpoints, are limited to 10 requests per second.
  • Rate Limits for Batch Import:
    • The Batch Import endpoints for Stops and Unassigned Stops models are limited to 10 requests per minute. However, these endpoints can handle the import of up to 1,000 stops per minute. The Creation, Update, and Deletion endpoints for these models still maintain a rate limit of 5 requests per second.
    • The Batch Import endpoint for Drivers is limited to 2 requests per minute. This allows for the import of up to 100 drivers per minute.
  • Rate Limits for Optimization Endpoints: The Plan optimization and re-optimization endpoints are limited to 3 requests per minute, due to the long running nature of these operations.

Spoke API will occasionally support bursts of requests, but they cannot be sustained and will be rejected if they last too long.

If Spoke rejects your request because it exceeds the rate limit, you must wait before retrying it. We suggest you use an exponential backoff approach for this.

We also recommend, besides the exponential backoff algorithm, that you add a random delay to each attempt to prevent a thundering herd problem.

If the client keeps retrying rate-limited requests while being rejected with a 429 at a high rate, Spoke will keep rejecting the requests until you turn down the request rate.

Spoke will also limit requests if it keeps receiving them at a high frequency at or close to the requests limit for an extended period, so while we support an occasional burst of requests, if this is sustained for a long period, we will rate-limit the client making them.

While we feel these rate-limits will work for the vast majority of use cases we understand every team is different. So please reach out to us and describe your use case if these limits are not enough for you, and we will evaluate increasing them for your team.

Stop Search API

Since V1 of the API, a new stop search endpoint is available. This endpoint allows searching across all stop documents (including unassigned stops), within your permitted data lifecycle.

The endpoint features full-text keyword search as well as a filtering DSL for including or excluding documents from the search.

Keywords

The most basic use of search is to simply provide keywords with the keyword parameter. This will perform a fuzzy full-text search across all applicable text fields in the stop documents and return the results sorted by relevance (by default).

For example:

?keyword=london

Filtering DSL

Filtering is performed with a simple, SQL-inspired language. It allows for precise queries using comparison operators and boolean logic.

For example (non-url-encoded for clarity):

?filter=address.placeId != "ChIJj61dQgK6j4AR4GeTYWZsKWw" and address.countryCode = "DE"

Syntax Overview

A filter expression consists of a field path, a comparison operator, and a value:

[field] [operator] [value]

Multiple expressions can be combined using boolean operators:

[condition1] and ([condition2] or [condition3])

Note on encoding: These expressions should be url-encoded before being passed to the API:

Supported Data Types

The DSL uses strictly typed fields and values. The following table describes the available data types and how to represent them in a filter string.

Type Description Examples
String Text values enclosed in double quotes. "active", "John Doe", "2026-01-01"
Integer Whole numbers, positive or negative. 123, -10, 0
Float Decimal numbers, positive or negative. 123.45, -33.8688
Boolean Logical values true or false. Case-insensitive. true, FALSE, True
Null Represents an empty or missing value. Case-insensitive. null, NULL

Comparison Operators

The following operators are available for comparing fields against values.

Operator Name Description Supported Types
= Equals Field value exactly matches the provided value. All types
!= Not Equals Field value does not match the provided value. All types
~= Phrase Match Field value contains the provided string (substring match). String
> Greater Than Field value is strictly greater than the provided value. String, Int, Float
>= Greater or Equal Field value is greater than or equal to the provided value. String, Int, Float
< Less Than Field value is strictly less than the provided value. String, Int, Float
<= Less or Equal Field value is less than or equal to the provided value. String, Int, Float

Note on String Comparisons: The operators >, >=, <, and <= can only be used with ISO-8601 date strings (e.g., createdAt > "2026-01-01").

Boolean Operators

Boolean operators allow you to combine multiple comparison filters into complex queries.

Operator Description Precedence
and Returns true if both conditions are met. 2 (Higher)
or Returns true if at least one condition is met. 1 (Lower)

Operators are case-insensitive (AND, and, And are all valid).

Grouping and Precedence

By default, and has higher precedence than or. You can use parentheses () to group conditions and override this behaviour.

  • a = 1 or b = 2 and c = 3 is evaluated as a = 1 or (b = 2 and c = 3).
  • (a = 1 or b = 2) and c = 3 forces the or condition to be evaluated first.

Fields and Paths

Fields represent the attribute of the resource you are filtering.

  • Nested Fields: Use dot notation to access nested attributes (e.g., address.countryCode).

Custom Properties

Teams can create custom properties for stops. These can be used in filters via the custom property's ID (not the name) as a nested field.

For example:

custom_property.0234-5678-0abc-def3 = "value"

To know the ID of a custom property, use the custom properties list endpoint.

Data Freshness

Note that data is ingested into the search index more slowly than the realtime API. This means a stop may not be immediately available in the search index after it is created. If you need to fetch a stop immediately, you should always use the stop restful resources e.g. fetch stop

Examples

The following are examples of valid, parsable filter strings (field names are examples and may not valid for stops):

  • Simple Equality: address.countryCode = "DE" - return all stops where the countryCode is exactly "DE".
  • Numeric Comparison: address.latitude >= 100 - return all stops where the latitude is greater than or equal to 100.
  • Substring Search: address ~= "London" - return all stops where the address contains "London".
  • Null Check: arrivalTime = null - return all stops where the arrivalTime field is not set.
  • Boolean Check: deliveryInfo.attempted = true - return all stops where deliveryInfo.attempted is set to true.
  • Combined Logic: address ~= "London" and address.countryCode = "GB" - return all stops where the address contains "London" and the country code is "GB".
  • Multiple Options: address ~= "London" or address ~= "Bristol" or address ~= "Manchester" - return all stops where the address contains either London, Bristol or Manchester.
  • Complex Grouping: (address ~= "London" or address ~= "Manchester") and (createdAt >= "2026-05-01T00:00:00Z" and createdAt < "2026-05-02T00:00:00Z") - return all stops where the address contains London or Manchester that were created on 2026-05-01.
  • Date Range: createdat >= "2026-05-01T00:00:00Z" and createdAt < "2026-06-01T00:00:00Z" - return all stops created in May 2026.

For code samples see Searching Stops

On the models

After this section you will find all the Spoke Public API endpoints available.

Every representation of resources that these endpoints create and return are documented in the Models page of the docs.

Plans

Endpoints to operate on Plans resources.

Create a new plan

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
required

The request body for creating a plan.

title
required
string [ 1 .. 255 ] characters
required
object

The date the plan starts. Does not accept dates that are too far in the future or past.

drivers
Array of strings <= 50 items [ items^drivers\/[a-zA-Z0-9---_]{1,50}$ ]
Default: []

The drivers IDs of the plan, in the format drivers/<id>, duplicates will be ignored

string or null

The depot id, in the format depots/<id>. If not provided, the team's Main Depot will be used.

object or null

Overrides for the plan route behavior.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "starts": {
    },
  • "drivers": [ ],
  • "depot": "string",
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "starts": {
    },
  • "depot": "string",
  • "distributed": true,
  • "writable": true,
  • "optimization": "creating",
  • "drivers": [
    ],
  • "routes": [
    ],
  • "routeOverrides": {
    }
}

List plans

Authorizations:
HTTP: BasicAuth
query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token, if any.

maxPageSize
number [ 1 .. 20 ]
Default: 10

The max page size.

object

The filter to apply to the list of plans. The filter params are passed like this: ?filter[title]=foo or like this: ?filter.title=foo

Responses

Response samples

Content type
application/json
{
  • "plans": [
    ],
  • "nextPageToken": "string"
}

Update an existing plan

Update an existing plan. If the plan writable property is false, prefer using the Live Plans API.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json

The request body for updating a plan. All the values present in the request will update the plan value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.

Important: Notice that the drivers Array will be completely replaced. If a single driver is provided in the request, the plan will have all other previous drivers discarded.

title
string [ 1 .. 255 ] characters
object

The date the plan starts. Does not accept dates that are too far in the future or past.

drivers
Array of strings <= 50 items [ items^drivers\/[a-zA-Z0-9---_]{1,50}$ ]

The drivers IDs of the plan, in the format drivers/<id>, duplicates will be ignored

string or null

The depot id, in the format depots/<id>. If not provided, the team's Main Depot will be used.

object or null

Overrides for the plan route behavior.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "starts": {
    },
  • "drivers": [
    ],
  • "depot": "string",
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "starts": {
    },
  • "depot": "string",
  • "distributed": true,
  • "writable": true,
  • "optimization": "creating",
  • "drivers": [
    ],
  • "routes": [
    ],
  • "routeOverrides": {
    }
}

Retrieve a plan

Retrieve a plan

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "starts": {
    },
  • "depot": "string",
  • "distributed": true,
  • "writable": true,
  • "optimization": "creating",
  • "drivers": [
    ],
  • "routes": [
    ],
  • "routeOverrides": {
    }
}

Delete a plan

Delete a plan and related routes. This action cannot be undone and will delete all the releated routes as well, even if the plan is not in a writable state. As this action is not atomic, it is possible that only partial deletion occurs if the endpoint errors out with a 500. In that case it is recommended to retry the request.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Optimize a plan

Optimize a plan. Returns the created operation, which can be polled for the result. Use the returned id with the operations endpoints to poll for the result.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "plan_optimization",
  • "done": true,
  • "metadata": {
    },
  • "result": {
    }
}

Distribute a plan

Distribute a plan to its drivers. This will send then their routes.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "starts": {
    },
  • "depot": "string",
  • "distributed": true,
  • "writable": true,
  • "optimization": "creating",
  • "drivers": [
    ],
  • "routes": [
    ],
  • "routeOverrides": {
    }
}

List plan stops

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token, if any.

maxPageSize
number [ 1 .. 10 ]
Default: 10

The max page size.

object

The filter to apply to the list of stops. The filter params are passed like this: ?filter[externalId]=foo or like this: ?filter.externalId=foo

Responses

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "nextPageToken": "string"
}

Stops

Endpoints to operate on Stop resources.

For any Plans created before 2023-04-01 the stop collections and all related operations will not be available.

For any operations here you will need a Plan ID beforehand. You can retrieve an existing Plan by listing your Plans or you can create a new one.

Create a new stop

Create a new stop with the given data. Prefer using the batch import endpoint if you want to create multiple stops at once as it is more efficient and will produce better geocoding results. If the plan is not writable, this will fail, prefer using the Live Create Stop API instead.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json
required

The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.

required
object
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

string or null

Client ID of the retailer in Spoke Connect

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "timing": {
    },
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "clientId": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "estimatedTravelDuration": 0,
  • "estimatedTravelDistance": 0,
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "type": "start",
  • "packageLabel": "string",
  • "stopPosition": 0,
  • "trackingLink": "string",
  • "webAppLink": "string",
  • "orderInfo": {
    },
  • "placeInVehicle": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "deliveryInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "plan": "string",
  • "route": {
    },
  • "eta": {
    },
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "customProperties": {
    },
  • "clientId": "string"
}

Batch import stops

Batch import stops. The request body must contain an array of stops to import. If the plan is not writable, the request will fail, prefer using the Import Live Stops API instead.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json

An array of stops to import in batch. Supports a maximum of 100 stops per request.

Array ([ 1 .. 100 ] items)
required
object
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

string or null

Client ID of the retailer in Spoke Connect

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}

Update an existing stop

Does not support updating a stop's location, nor the clientId. To do so, delete the stop and create a new one. If the plan is not writable, the request will fail, prefer using the Update Live Stops API instead.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

stopId
required
string^[a-zA-Z0-9---_]{1,50}$

The stop id

Request Body schema: application/json

The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.

object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

object or null

Responses

Request samples

Content type
application/json
{
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    },
  • "timing": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "estimatedTravelDuration": 0,
  • "estimatedTravelDistance": 0,
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "type": "start",
  • "packageLabel": "string",
  • "stopPosition": 0,
  • "trackingLink": "string",
  • "webAppLink": "string",
  • "orderInfo": {
    },
  • "placeInVehicle": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "deliveryInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "plan": "string",
  • "route": {
    },
  • "eta": {
    },
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "customProperties": {
    },
  • "clientId": "string"
}

Retrieve a stop

Retrieve a stop

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

stopId
required
string^[a-zA-Z0-9---_]{1,50}$

The stop id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "estimatedTravelDuration": 0,
  • "estimatedTravelDistance": 0,
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "type": "start",
  • "packageLabel": "string",
  • "stopPosition": 0,
  • "trackingLink": "string",
  • "webAppLink": "string",
  • "orderInfo": {
    },
  • "placeInVehicle": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "deliveryInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "plan": "string",
  • "route": {
    },
  • "eta": {
    },
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "customProperties": {
    },
  • "clientId": "string"
}

Delete a stop

Delete a stop. This action cannot be undone and will delete all the data associated with the stop. If the plan is not writable, this will fail, prefer using the Live Delete Stop API instead.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

stopId
required
string^[a-zA-Z0-9---_]{1,50}$

The stop id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Stop Search

See the Stops Search docs for more information on formatting the filter string. The following fields are filterable:

  • planId - The ID of the plan stop is linked to in PlanId format (e.g. plans/{planId})
  • routeId - The ID of the route stop is linked to in RouteId format (e.g. routes/{routeId})
  • type - The type of the stop (e.g. start, stop, end)
  • activity - The activity performed at the stop (delivery or pickup)
  • notes - Notes associated with the stop
  • orderInfo.sellerOrderId - The order ID from the seller
  • orderInfo.sellerWebsite - The website URL of the seller
  • address.address - The full address of the stop
  • address.addressLineOne - The first line of the stop address
  • address.addressLineTwo - The second line of the stop address
  • address.latitude - The latitude of the stop address in decimal degrees
  • address.longitude - The longitude of the stop address in decimal degrees
  • address.placeId - The Google Places identifier for the address
  • address.countryCode - The ISO country code for the address
  • createdAt - The timestamp when the stop was created (ISO 8601)
  • arrivalAt - The timestamp of the (estimated) arrival at the stop (ISO 8601)
  • packageCount - The number of packages to be delivered or picked up
  • estimatedTravelDuration - The estimated travel time to this stop from the previous one, in seconds
  • estimatedTravelDistance - The estimated travel distance to this stop from the previous one, in meters
  • timing.estimatedAttemptDuration - The estimated time spent at the stop to perform the activity, in seconds
  • recipient.name - The name of the recipient at the stop
  • recipient.email - The email address of the recipient
  • recipient.phone - The phone number of the recipient
  • recipient.externalId - An external identifier for the recipient
  • deliveryInfo.state - The current state of the delivery (e.g. delivered_to_recipient, failed_not_home)
  • deliveryInfo.attempted - Whether a delivery attempt has been made
  • deliveryInfo.succeeded - Whether the delivery was successful
  • deliveryInfo.recipientProvidedNotes - Notes provided by the recipient for the driver
  • deliveryInfo.driverProvidedInternalNotes - Internal notes provided by the driver
  • deliveryInfo.driverProvidedRecipientNotes - Notes for the recipient provided by the driver
  • deliveryInfo.signeeName - The name of the person who signed for the delivery
  • deliveryInfo.attemptedAt - The timestamp when the delivery was attempted (ISO 8601)
  • orderInfo.products - The list of products included in the order
  • orderInfo.sellerName - The name of the seller
  • paymentOnDelivery.amount - The amount to be collected on delivery, in original units
  • barcodes - The list of barcodes associated with the stop
  • packageLabel - The label applied to the package(s)
  • customProperties.* - A custom property of the stop. Replace * with the custom property ID.

The following fields are sortable:

  • address.latitude
  • address.longitude
  • createdAt
  • arrivalAt
  • packageCount
  • estimatedTravelDuration
  • estimatedTravelDistance
  • timing.estimatedAttemptDuration
  • deliveryInfo.attemptedAt
  • paymentOnDelivery.amount
Authorizations:
HTTP: BasicAuth
query Parameters
keyword
string [ 1 .. 255 ] characters

Keywords to include in the search. These will be applied to all applicable text fields using a fuzzy matching.

filter
string [ 1 .. 2048 ] characters

The filter to apply. This is used to include/exclude stops form the search.

pageToken
string

The page token.

maxPageSize
integer ( 1 .. 20 )
Default: 20

The max page size.

sortField
string

The sort field.

sortOrder
string
Default: "asc"
Enum: "asc" "desc"

The sort direction.

Responses

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "nextPageToken": "string"
}

Unassigned Stops

Endpoints to operate on Unassigned Stop resources.

Retrieve an unassigned stop

Retrieve an unassigned stop

Authorizations:
HTTP: BasicAuth
path Parameters
unassignedStopId
required
string^[a-zA-Z0-9---_]{1,50}$

The unassigned stop id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "depot": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "orderInfo": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "trackingLink": "string",
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "customProperties": {
    },
  • "clientId": "string"
}

Delete an unassigned stop

Delete an unassigned stop. This action cannot be undone and will delete all the data associated with the unassigned stop.

Authorizations:
HTTP: BasicAuth
path Parameters
unassignedStopId
required
string^[a-zA-Z0-9---_]{1,50}$

The unassigned stop id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Update an existing unassigned stop

Does not support updating a unassigned stop's location, nor the clientId. To do so, delete the unassignedStop and create a new one.

Authorizations:
HTTP: BasicAuth
path Parameters
unassignedStopId
required
string^[a-zA-Z0-9---_]{1,50}$

The unassigned stop id

Request Body schema: application/json

The request body for updating an unassigned stop. All the values present in the request will update the unassigned stop value. If you wish to update only certain fields, only set those and do not set the others. Any fields not set will not be updated.

object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

object or null
string or null

The Depot ID that this unassigned stop belongs to, in the format depot/<id>. If null, it will default to the team's main depot. If not provided, it will not be updated.

Responses

Request samples

Content type
application/json
{
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    },
  • "timing": {
    },
  • "depot": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "depot": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "orderInfo": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "trackingLink": "string",
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "customProperties": {
    },
  • "clientId": "string"
}

List unassigned stops

Authorizations:
HTTP: BasicAuth
query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token to continue from.

maxPageSize
number [ 1 .. 20 ]
Default: 20

The maximum number of unassigned stops to return per page.

object

The filter to apply to the list of unassigned stops.

Responses

Response samples

Content type
application/json
{
  • "unassignedStops": [
    ],
  • "nextPageToken": "string"
}

Create a new unassigned stop

Create a new unassigned stop with the given data.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
required

The request body for creating an unassigned stop. Address is a required field, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set (and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be. The depotId field is not required, but will default to the main depot of the team if not provided, be sure to provide it if you want to use a different depot.

required
object
string or null

The Depot ID that this unassigned stop belongs to, in the format depot/<id>. If not provided, or null, it will default to the team's main depot.

object or null
object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

string or null

Client ID of the retailer in Spoke Connect

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "depot": "string",
  • "timing": {
    },
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "clientId": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "depot": "string",
  • "address": {
    },
  • "barcodes": [
    ],
  • "allowedDrivers": [
    ],
  • "notes": "string",
  • "packageCount": 0,
  • "weight": {
    },
  • "orderInfo": {
    },
  • "recipient": {
    },
  • "activity": "delivery",
  • "trackingLink": "string",
  • "timing": {
    },
  • "optimizationOrder": "first",
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "customProperties": {
    },
  • "clientId": "string"
}

Batch import unassigned stops

Batch import unassigned stops. The request body must contain an array of unassigned stops to import. Note that the depot is the same for all unassigned stops in a same request. This is because the depot is used as a biasing location for the unassigned stops, so that the geocoding results are more accurate for a same region.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
required
required
Array of objects [ 1 .. 100 ] items

An array of unassigned stops to import in batch. Supports a maximum of 100 unassigned stops per request. Note that the depot is shared across all unassigned stops in the request, and thus should not be provided for individual unassigned stops. That is because the depot location is used to bias the geocoding results of the stops.

string or null

The Depot ID the unassigned stops in the batch belong to, in the format depot/<id>. This is used to bias the geocoding results of the unassigned stops, so every unassigned stop in the batch should belong to the same depot. If not provided, or null, it will default to the team's main depot.

Responses

Request samples

Content type
application/json
{
  • "unassignedStops": [
    ],
  • "depot": "string"
}

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}

Live Plans

Endpoints to operate on Plans resources when it's pending re-optimization and re-distribution.

You must use these endpoints to apply the changes when any Live Stops request returns pending = true.

Re-optimize a plan

Re-optimize a plan. This endpoint should be used only after updating a live plan. Returns the created operation, which can be polled for the result. Use the returned id with the operations endpoints to poll for the result.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json

The request body for reoptimize a plan.

optimizationType
string
Default: "reorder_changed_stops"
Enum: "reorder_changed_stops" "reorder_all_stops" "redistribute_stops_between_drivers"

The type of optimization to use

Responses

Request samples

Content type
application/json
{
  • "optimizationType": "reorder_changed_stops"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "plan_optimization",
  • "done": true,
  • "metadata": {
    },
  • "result": {
    }
}

Re-distribute a plan

Re-distribute a plan to its drivers. This endpoint should be used only after updating a live plan. This will apply the re-optimization changes and send the drivers their routes.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "starts": {
    },
  • "depot": "string",
  • "distributed": true,
  • "writable": true,
  • "optimization": "creating",
  • "drivers": [
    ],
  • "routes": [
    ],
  • "routeOverrides": {
    }
}

Save the plan changes

Save the plan changes after re-optimization without distributing it. This endpoint is optional since re-distribute already saves the changes.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Live Stops

Endpoints to operate on Stop resources when the plan is already optimized and therefore not writable.

All the endpoints return the field pending. This field indicates whether the change has been applied to the plan or if it's pending a new optimization and distribution. On pending = true, you must use the re-optimize and re-distribute endpoints to apply the changes to the plan.

Create a new stop

Create a new stop with the given data on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. Prefer using the batch import endpoint if you want to create multiple stops at once as it is more efficient and will produce better geocoding results.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json
required

The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.

required
object
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

string or null

Client ID of the retailer in Spoke Connect

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "timing": {
    },
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "clientId": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    }
}

Response samples

Content type
application/json
{
  • "pending": true,
  • "stop": {
    }
}

Update an existing stop

Update a stop on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. It does not support updating a stop's location, nor the clientId. To do so, delete the stop and create a new one.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

stopId
required
string^[a-zA-Z0-9---_]{1,50}$

The stop id

Request Body schema: application/json

The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.

object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

object or null

Responses

Request samples

Content type
application/json
{
  • "recipient": {
    },
  • "orderInfo": {
    },
  • "paymentOnDelivery": {
    },
  • "proofOfAttemptRequirements": {
    },
  • "allowedDrivers": [
    ],
  • "activity": "delivery",
  • "optimizationOrder": "first",
  • "packageCount": 1,
  • "weight": {
    },
  • "notes": "string",
  • "barcodes": [
    ],
  • "customProperties": {
    },
  • "timing": {
    }
}

Response samples

Content type
application/json
{
  • "pending": true,
  • "stop": {
    }
}

Batch import stops

Import stops to live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

Request Body schema: application/json

An array of stops to import in batch. Supports a maximum of 100 stops per request.

Array ([ 1 .. 100 ] items)
required
object
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.

string or null
Default: "delivery"

Activity type

string or null

The preferred order of this stop in the optimized route. If not provided or "default", the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either "first" or "last".

number or null

Number of packages in the stop

object or null

Weight information for this stop.

string or null

Notes for the stop

string or null

Client ID of the retailer in Spoke Connect

barcodes
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

List of barcode IDs associated with this stop

object or null

Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ],
  • "pending": true
}

Delete a stop

Delete a stop on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded.

Authorizations:
HTTP: BasicAuth
path Parameters
planId
required
string^[a-zA-Z0-9---_]{1,50}$

The plan id

stopId
required
string^[a-zA-Z0-9---_]{1,50}$

The stop id

Responses

Response samples

Content type
application/json
{
  • "pending": true
}

Drivers

Endpoints to operate on Drivers resources.

List Drivers

Authorizations:
HTTP: BasicAuth
query Parameters
maxPageSize
number [ 1 .. 50 ]
Default: 50

The maximum number of drivers to return.

pageToken
string [ 1 .. 255 ] characters

The page token to continue from.

object

The filter to apply to the list of drivers. The filter param is passed like this: ?filter[active]=true or like this: ?filter.active=true

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ],
  • "nextPageToken": "string"
}

Create a new driver

Create a driver with the given data in your team. Prefer using the batch import endpoint for creating multiple drivers at once as it is more efficient, faster.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
string or null

The driver's full name

string or null

The name displayed for the driver in the UI

string or null

Driver's email

string or null

Driver's phone number

Array of strings or null

The depot IDs associated with the driver in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.

object or null

Overrides for the driver route behavior.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "depots": [
    ],
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "phone": "string",
  • "displayName": "string",
  • "active": true,
  • "depots": [
    ],
  • "routeOverrides": {
    }
}

Retrieve a driver

Authorizations:
HTTP: BasicAuth
path Parameters
driverId
required
string^[a-zA-Z0-9---_]{1,50}$

The driver id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "phone": "string",
  • "displayName": "string",
  • "active": true,
  • "depots": [
    ],
  • "routeOverrides": {
    }
}

Remove a driver

Removes a driver from your team. If the driver also has dashboard access, the driver will only have their "driver" role revoked; thus not being listed among the team drivers, but will keep their dashboard access.

Authorizations:
HTTP: BasicAuth
path Parameters
driverId
required
string^[a-zA-Z0-9---_]{1,50}$

The driver id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Update a driver

Updates a driver from your team. The member must have the "driver" role.

Authorizations:
HTTP: BasicAuth
path Parameters
driverId
required
string^[a-zA-Z0-9---_]{1,50}$

The driver id

Request Body schema: application/json

The request body for updating a driver.

string or null

The driver's full name

string or null

The name displayed for the driver in the UI

Array of strings or null

The depot IDs associated with the driver in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.

object or null

Overrides for the driver route behavior.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "depots": [
    ],
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "phone": "string",
  • "displayName": "string",
  • "active": true,
  • "depots": [
    ],
  • "routeOverrides": {
    }
}

Batch import drivers

Creates multiple drivers in your team. The request body must contain an array of drivers to import.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json

An array of driver descriptions to be created in batch.

Array ([ 1 .. 50 ] items)
string or null

The driver's full name

string or null

The name displayed for the driver in the UI

string or null

Driver's email

string or null

Driver's phone number

Array of strings or null

The depot IDs associated with the driver in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.

object or null

Overrides for the driver route behavior.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}

Depots

Endpoints to operate on Depots resources.

This resource is currently read-only on the API.

Create a depot

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 2048 ] characters
required
object

Defines some default parameters for routes originating from this depot

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "routeOverrides": {
    }
}

List Depots

Authorizations:
HTTP: BasicAuth
query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token to continue from.

maxPageSize
number [ 1 .. 20 ]
Default: 20

The maximum number of depots to return.

Responses

Response samples

Content type
application/json
{
  • "depots": [
    ],
  • "nextPageToken": "string"
}

Retrieve a depot

Authorizations:
HTTP: BasicAuth
path Parameters
depotId
required
string^[a-zA-Z0-9---_]{1,50}$

The depot id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "routeOverrides": {
    }
}

Remove a depot

Authorizations:
HTTP: BasicAuth
path Parameters
depotId
required
string^[a-zA-Z0-9---_]{1,50}$

The depot id

Responses

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Update a depot

Authorizations:
HTTP: BasicAuth
path Parameters
depotId
required
string^[a-zA-Z0-9---_]{1,50}$

The depot id

Request Body schema: application/json

The request body for updating a depot. All the values present in the request will update the depot value; if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.

name
string [ 1 .. 2048 ] characters
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "routeOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "routeOverrides": {
    }
}

Batch import depots

Batch import depots. The request body must contain an array of depots to import.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json

An array of depots to import in batch. Supports a maximum of 100 depots per request.

Array ([ 1 .. 100 ] items)
name
required
string [ 1 .. 2048 ] characters
required
object

Defines some default parameters for routes originating from this depot

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}

Set the main depot for the team

Authorizations:
HTTP: BasicAuth
path Parameters
depotId
required
string^[a-zA-Z0-9---_]{1,50}$

The depot id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "url": "string"
}

Routes

Endpoints to operate on Routes resources.

This resource is currently read-only on the API.

Retrieve a route

Authorizations:
HTTP: BasicAuth
path Parameters
routeId
required
string^[a-zA-Z0-9---_]{1,50}$

The route id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "stopCount": 0,
  • "driver": "string",
  • "state": {
    },
  • "plan": "string"
}

List Routes

Authorizations:
HTTP: BasicAuth
query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token to continue from.

maxPageSize
number [ 1 .. 20 ]
Default: 20

The maximum number of routes to return.

Responses

Response samples

Content type
application/json
{
  • "routes": [
    ],
  • "nextPageToken": "string"
}

List route stops

Authorizations:
HTTP: BasicAuth
path Parameters
routeId
required
string^[a-zA-Z0-9---_]{1,50}$

The route id

query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token, if any.

maxPageSize
number [ 1 .. 10 ]
Default: 10

The max page size.

object

The filter to apply to the list of stops. The filter params are passed like this: ?filter[externalId]=foo or like this: ?filter.externalId=foo

Responses

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "nextPageToken": "string"
}

Operations

Endpoints to operate on Operations resources.

Cancel an operation

Cancel an operation that is not yet done.

Authorizations:
HTTP: BasicAuth
path Parameters
operationId
required
string^[a-zA-Z0-9---_]{1,50}$

The ID of the operation to cancel.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "plan_optimization",
  • "done": true,
  • "metadata": {
    },
  • "result": {
    }
}

Retrieve an operation

Authorizations:
HTTP: BasicAuth
path Parameters
operationId
required
string^[a-zA-Z0-9---_]{1,50}$

The ID of the operation to cancel.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "plan_optimization",
  • "done": true,
  • "metadata": {
    },
  • "result": {
    }
}

List operations

Authorizations:
HTTP: BasicAuth
query Parameters
pageToken
string [ 1 .. 255 ] characters

The page token to continue from.

maxPageSize
number [ 1 .. 20 ]
Default: 20

The maximum number of operations to return per page.

object

The filter to apply to the list of operations.

Responses

Response samples

Content type
application/json
{
  • "operations": [
    ],
  • "nextPageToken": "string"
}

Team

Endpoints to retrieve Custom Stop Properties.

List custom stop properties

Returns a list of custom stop properties definitions.

Authorizations:
HTTP: BasicAuth

Responses

Response samples

Content type
application/json
{
  • "customStopProperties": [
    ]
}

Retrieve a custom stop property

Returns a custom stop property definition.

Authorizations:
HTTP: BasicAuth
path Parameters
customStopPropertyId
required
string <= 50 characters

The custom stop property id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "visibleToDrivers": true,
  • "visibleToRecipients": true
}

Members

Endpoints to operate on Members resources.

Create a new member

Create a member with the given data in your team. Prefer using the batch import endpoint for creating multiple members at once as it is more efficient.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json
required
string or null

The member's full name

string or null

The name displayed for the member in the UI

string or null

Member's email

string or null

The existing driver to link the member to

role
required
string
Enum: "admin" "depot-manager" "dispatcher" "read-only"

The operational role given to the member.

Array of strings or null

The depot IDs associated with the member in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "email": "user@example.com",
  • "linkedDriverId": "string",
  • "role": "admin",
  • "depots": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "phone": "string",
  • "linkedDriverId": "string",
  • "displayName": "string",
  • "active": true,
  • "depots": [
    ],
  • "roles": [
    ]
}

Update a member

Updates a member from your team.

Authorizations:
HTTP: BasicAuth
path Parameters
memberId
required
string^[a-zA-Z0-9---_]{1,50}$

The member id

Request Body schema: application/json

The request body for updating a member.

string or null

The member's full name

string or null

The name displayed for the member in the UI

string or null

The operational role given to the member.

Array of strings or null

The depot IDs associated with the member in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "role": "admin",
  • "depots": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "phone": "string",
  • "linkedDriverId": "string",
  • "displayName": "string",
  • "active": true,
  • "depots": [
    ],
  • "roles": [
    ]
}

Remove a member

Removes a member from your team. If the member also has driver access, the member will only have their operational role(s) revoked; thus not being listed among the team members, but will keep their driver access.

Authorizations:
HTTP: BasicAuth
path Parameters
memberId
required
string^[a-zA-Z0-9---_]{1,50}$

The member id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "param": "string",
  • "url": "string"
}

Import multiple members

Import multiple members at once.

Authorizations:
HTTP: BasicAuth
Request Body schema: application/json

An array of member descriptions to be created in batch.

Array ([ 1 .. 50 ] items)
string or null

The member's full name

string or null

The name displayed for the member in the UI

string or null

Member's email

string or null

The existing driver to link the member to

role
required
string
Enum: "admin" "depot-manager" "dispatcher" "read-only"

The operational role given to the member.

Array of strings or null

The depot IDs associated with the member in the format depots/<id>, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}