EasyRoutes Routes API (Beta)
EasyRoutes API is currently in closed beta. Please contact us if you are interested in early access!
Please see our API Getting Started Guide to enable API access and set up your client key.
Endpoints
Authenticate
POST |
https://easyroutes.roundtrip.ai/api/2024-07/authenticate |
Authenticate a client to obtain an access token using a client ID and secret key. The access token is required to make authenticated requests to the API. The token will expire after the duration specified in the response.
curl -X POST -H "Content-Type: application/json" \
-d '{"clientId": "...", "clientSecret": "..."}' \
https://easyroutes.roundtrip.ai/api/2024-07/authenticate
Request Body
Field |
Type |
Description |
clientId |
string |
The client ID from EasyRoutes settings. |
clientSecret |
string |
The client secret from EasyRoutes settings. |
Response
Field |
Type |
Description |
accessToken |
string |
The access token to use for authenticated requests. |
expiresInSeconds |
int64 |
The duration in seconds until the access token expires. |
ListRoutes
GET |
https://easyroutes.roundtrip.ai/api/2024-07/routes |
Fetch a list of routes based on the provided query. The query may include a limit, sort key, timestamp bounds, and whether to include archived routes. The response will include a list of routes and a cursor to fetch the next page of results. Subsequent requests should include the cursor only and no list query arguments (which are encoded in the cursor). This request requires authentication via an access token provided in the Authorization: Bearer ...
header.
curl -H "Authorization: Bearer ..." \
https://easyroutes.roundtrip.ai/api/2024-07/routes?query.sortKey=UPDATED_AT&query.limit=10
Query Parameters
Field |
Type |
Description |
query.limit |
int32 |
Maximum number of routes to return. Must be less than or equal to 200 . Defaults to 20 . |
query.sortKey |
RouteSortKey |
Sort key for the returned routes. This determines the ordering of returned routes. |
query.timestampStart |
string (RFC3339 format) |
Lower bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key. |
query.timestampEnd |
string (RFC3339 format) |
Upper bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key. |
query.includeArchived |
bool |
Whether to include archived routes in the results. |
cursor |
string |
Must be empty on initial request, must be set on subsequent. |
Response
Field |
Type |
Description |
routes |
Route[] |
List of routes. |
nextCursor |
string |
Cursor to fetch the next page of results (if available). |
GetRoute
GET |
https://easyroutes.roundtrip.ai/api/2024-07/routes/{id} |
Fetch a single route by ID. This request requires authentication via an access token provided in the Authorization: Bearer ...
header.
curl -H "Authorization: Bearer ..." \
https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939
Path Parameters
Field |
Type |
Description |
id |
string |
The route ID to fetch. |
Response
Route
GetRouteStop
GET |
https://easyroutes.roundtrip.ai/api/2024-07/routes/{route_id}/stops/{stop_id} |
Fetch a single stop on a route by route ID and stop ID. This request requires authentication via an access token provided in the Authorization: Bearer ...
header.
curl -H "Authorization: Bearer ..." \
https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939/stops/rst-9817a456-e6fd-4652-b918-5dc89d3621d3
Path Parameters
Field |
Type |
Description |
routeId |
string |
The route ID containing the stop. |
stopId |
string |
The stop ID to fetch. |
Response
RouteStop
ImportStops
POST |
https://easyroutes.roundtrip.ai/api/2024-07/stops/import |
Import stops into EasyRoutes from an external source. The request requires authentication via an access token provided in the Authorization : Bearer ...
header. The request body should include a list of stops to import. The response will include a list of imported stops with generated IDs. The maximum number of stops to import in a single request is 200
.
curl -X POST -H "Authorization: Bearer ..." \
-H "Content-Type: application/json" \
-d '[
{
"address": {
"address1": "123 Main St",
"city": "New York",
"provinceCode": "NY",
"countryCode": "US",
"zip": "10001"
},
"contact": {
"firstName": "John",
"lastName": "Doe",
"phone": "+14265551000",
"email": "john.doe@roundtrip.ai"
},
"items": [
{
"name": "Bananas",
"quantity": 5,
"grams": 500
}
],
"note": "Leave at front door",
"duration": "300s",
"priority": 5,
"orderName": "#123"
}
]' \
https://easyroutes.roundtrip.ai/api/2024-07/stops/import
Request Body
StopToImport[]
Response
Field |
Type |
Description |
stops |
ImportedStop[] |
The list of imported stops with generated IDs. |
Data Types
Address
Field |
Type |
Description |
address1 |
string |
Street address line 1 (e.g. "123 Main St" ). |
address2 |
string |
Street address line 2 (e.g. "Apt 101" ). |
city |
string |
City name (e.g. "New York" ). |
provinceCode |
string |
Province or state code (e.g. "NY" ). |
countryCode |
string |
Country code (e.g. "US" ). |
zip |
string |
Postal or ZIP code (e.g. "10001" ). |
BreakStatus
Value |
Description |
UNKNOWN |
Unknown break status (not completed). |
COMPLETED |
Break stop has been completed. |
Field |
Type |
Description |
firstName |
string |
First name (e.g. "John" ). |
lastName |
string |
Last name (e.g. "Doe" ). |
company |
string |
Company name (e.g. "Roundtrip Systems Inc" ). |
phone |
string |
Phone number (e.g. "+14265551000" ). |
email |
string |
Email address (e.g. "john.doe@roundtrip.ai" ) |
DeliveryStatus
Value |
Description |
UNKNOWN |
Unknown delivery status (not marked as ready). |
DELIVERED |
Stop was delivered. |
OUT_FOR_DELIVERY |
Stop is out for delivery. |
ATTEMPTED_DELIVERY |
Stop delivery was attempted. |
READY_FOR_DELIVERY |
Stop is ready for delivery. |
Driver
Field |
Type |
Description |
id |
string |
Driver ID (e.g. "drv-123e4567-e89b-12d3-a456-426614174000" ). |
firstName |
string |
Driver first name (e.g. "John" ). |
lastName |
string |
Driver last name (e.g. "Doe" ). |
ImportedStop
Field |
Type |
Description |
id |
string |
The ID of the imported stop, generated by EasyRoutes (e.g. "ist-123e4567-e89b-12d3-a456-426614174000" ). |
address |
Address |
The address for the stop. |
contact |
Contact |
The contact information for the stop. |
coordinates |
LatLng |
The coordinates to use for the stop, if provided on import. |
items |
StopItem[] |
The items to deliver at the stop. |
note |
string |
A note for the stop. |
duration |
string |
Planned duration of the stop. |
priority |
int32 |
Priority of the stop for route planning. |
orderName |
string |
The name of the order associated with the stop. |
importedAt |
string (RFC3339 format) |
The timestamp at which the stop was imported. |
LatLng
Field |
Type |
Description |
latitude |
double |
The latitude in degrees. It must be in the range [-90.0, +90.0]. |
longitude |
double |
The longitude in degrees. It must be in the range [-180.0, +180.0]. |
Route
Field |
Type |
Description |
id |
string |
Route ID (e.g. "rte-123e4567-e89b-12d3-a456-426614174000" ). |
name |
string |
Route name (e.g. "Morning route" ). |
driver |
Driver |
Assigned driver for the route. |
start |
RouteStart |
Route start address and tasks. |
end |
RouteEnd |
Route end address and tasks. |
stops |
RouteStop[] |
Route stops. See RouteStop for stop fields. |
createdAt |
string (RFC3339 format) |
Timestamp when the route was created. |
updatedAt |
string (RFC3339 format) |
Timestamp when the route was last updated (by the planner). |
archivedAt |
string (RFC3339 format) |
Timestamp when the route was archived. |
scheduledFor |
string (RFC3339 format) |
Timestamp when the route is scheduled for. |
RouteEnd
Field |
Type |
Description |
address |
Address |
The end address of the route. |
tasks |
Task[] |
Tasks to complete before finishing the route. |
RouteSortKey
Value |
Description |
UNKNOWN |
Unknown sort key (not provided or unrecognized). |
CREATED_AT |
Sort by route creation time. |
UPDATED_AT |
Sort by route update time. |
RouteStart
Field |
Type |
Description |
address |
Address |
The start address of the route. |
tasks |
Task[] |
Tasks to complete before starting the route. |
RouteStop
Field |
Type |
Description |
id |
string |
Stop ID (e.g. "rst-123e4567-e89b-12d3-a456-426614174000" ). |
type |
StopType |
The type of stop (DELIVERY or BREAK). |
deliveryStatus |
DeliveryStatus |
The status for DELIVERY stops. |
breakStatus |
BreakStatus |
The status for BREAK stops. |
updatedAt |
string (RFC3339 format) |
Timestamp when the stop was last updated. |
duration |
string |
Planned duration of the stop in seconds. |
plannedArrival |
string (RFC3339 format) |
Planned arrival time at the stop. |
note |
string |
Note for the stop. |
address |
Address |
Delivery address for the stop. |
contact |
Contact |
Contact information for the stop delivery recipient. |
plannedCoordinates |
LatLng |
Planned coordinates for the stop. |
items |
StopItem[] |
Items to deliver at the stop. |
source |
StopSource |
The source of the stop, which may be populated for DELIVERY stops. The source can be a SHOPIFY_ORDER , an EasyRoutes SAVED_STOP , or an IMPORTED_STOP from an external source (such as CSV file). |
shopifyOrderId |
int64 |
The Shopify order ID, populated when the stop source is a SHOPIFY_ORDER . |
savedStopId |
string |
The saved stop ID, populated when the stop source is a SAVED_STOP . |
deliveredCoordinates |
LatLng |
Delivered coordinates for the stop. |
proofOfDeliveryNote |
string |
Proof of delivery note for the stop. |
proofOfDeliveryPhotos |
StopAttachment[] |
Proof of delivery photos for the stop. Photos may be fetched using the URLs on the attachments. |
proofOfDeliverySignatures |
StopAttachment[] |
Proof delivery signatures for the stop. Signatures may be fetched using the URLs on the attachments. |
tasks |
Task[] |
Driver tasks for the stop, included completed items and any input from the driver. |
priority |
int32 |
Priority of the stop for route planning. The valid range for stop priority is between 1 (low) and 10 (high), with default priority corresponding to a value of 5 . A priority value of 0 is considered unset and is treated the same as "default" priority. Stops with higher priority will be preferred when generating routes with constraints. |
importedStopId |
string |
The imported stop ID, populated when the stop source is IMPORTED_STOP . |
StopAttachment
Field |
Type |
Description |
id |
string |
Attachment ID (e.g. "att-123e4567-e89b-12d3-a456-426614174000" ). |
createdAt |
string (RFC3339 format) |
Timestamp when the attachment was created. |
url |
string |
URL to fetch the attachment. |
StopItem
Field |
Type |
Description |
name |
string |
Item name (e.g. "Bananas" ). |
quantity |
int32 |
Quantity of the item (e.g. 5 ). |
grams |
int32 |
Weight of the item in grams (e.g. 500 ). |
StopSource
Value |
Description |
UNKNOWN |
Unknown stop source. |
SHOPIFY_ORDER |
Stop was created from a Shopify order. |
SAVED_STOP |
Stop was created from a saved stop in EasyRoutes. |
IMPORTED_STOP |
Stop was imported from an external source (i.e. CSV file). |
StopToImport
Field |
Type |
Description |
address |
Address |
The address for the stop. |
contact |
Contact |
The contact information for the stop. |
coordinates |
LatLng |
(Optional) The coordinates for the stop. If not provided, the coordinates will be geocoded from the address when the stop is added to a route. |
items |
StopItem[] |
The items to deliver at the stop. |
note |
string |
A note for the stop. |
duration |
string |
Planned duration of the stop. |
priority |
int32 |
Priority of the stop for route planning. The valid range for stop priority is between 1 (low) and 10 (high), with default priority corresponding to a value of 5 . A priority value of 0 is considered unset and is treated the same as "default" priority. Stops with higher priority will be preferred when generating routes with constraints. |
orderName |
string |
The name of the order associated with the stop, which can serve as an external reference to the order name / ID outside of EasyRoutes. This field is optional and EasyRoutes does not enforce uniqueness of order names. |
StopType
Value |
Description |
UNKNOWN |
Unknown stop type. |
DELIVERY |
Delivery stop. |
BREAK |
Break stop. |
PICKUP |
Pickup stop. |
TASK |
Task stop. |
Task
Field |
Type |
Description |
id |
string |
Task ID (e.g. "tsk-123e4567-e89b-12d3-a456-426614174000" ). |
title |
string |
Task title (e.g. "Delivery checklist" ). |
type |
TaskType |
Task type. |
items |
TaskItem[] |
Task items (populated for CHECKBOXES and RADIO_BUTTONS ). |
input |
TaskInput |
Task input (populated for TEXT_INPUT and DECIMAL_INPUT) . |
requiredToMarkStopAsDelivered |
bool |
Whether the task is required to mark the stop as delivered. In the case of tasks on RouteStart , this represents tasks required for starting the route. In the case of tasks on RouteEnd , this represents tasks required for completing the route. |
requiredToMarkStopAsAttempted |
bool |
Whether the task is required to mark the stop as attempted. |
Field |
Type |
Description |
value |
string |
Input value. |
updatedAt |
string (RFC3339 format) |
Timestamp when the input was last updated. |
TaskItem
Field |
Type |
Description |
id |
string |
Item ID (e.g. "itm-123e4567-e89b-12d3-a456-426614174000" ). |
title |
string |
Item title (e.g. "Pick up package" ). |
complete |
bool |
Whether the item is completed. |
updatedAt |
string (RFC3339 format) |
Timestamp when the item was last updated. |
TaskType
Value |
Description |
UNKNOWN |
Unknown task type. |
CHECKBOXES |
Task with checkboxes (multiple items to be completed). |
RADIO_BUTTONS |
Task with radio buttons (single item to be selected). |
TEXT_INPUT |
Task with driver text input (free-form text). |
DECIMAL_INPUT |
Task with driver decimal input. |