EasyRoutes Routes API

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 (encoded as string) 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 ID of the route 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/imports

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": "+14165551000",
           "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/imports

Request Body

StopToImport[]

Response

Field Type Description
stops ImportedStop[] The list of imported stops with generated IDs.

ListImportedStops

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports

Fetch a list of imported stops. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The response will include a list of imported stops 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). 

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports?query.limit=10

Query Parameters

Field Type Description
query.limit int32 Maximum number of imported stops to return. Must be less than or equal to 200. Defaults to 20.
cursor string Cursor to fetch the next page of results (if available). Should only be set on subsequent requests.

Response

Field Type Description
stops ImportedStop[] List of imported stops.
nextCursor string Cursor to fetch the next page of results (if available).

GetImportedStop

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}

Fetch a single imported stop by ID. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id. 

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000
or 
 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123

Path Parameters

Field Type Description
id string The ID of the imported stop to fetch. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

ImportedStop

DeleteImportedStop

DELETE https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}

Delete an imported stop by ID. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id. 

 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000
or 
 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123

Query Parameters

Field Type Description
id string The ID of the imported stop to delete. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

Empty

GetImportedStopRouteInfo

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}/routes

Fetch the route and stop IDs for an imported stop that has been added to one or more routes. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id. Note that this only returns routes updated in the last 30 days that are not deleted. 

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000/routes
or 
 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123/routes

Path Parameters

Field Type Description
id string The ID of the imported stop to fetch route info. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

Field Type Description
id string The ID of the imported stop.
routeInfo ImportedStopRouteInfo[] The route and stop IDs for the imported stop that has been added to a route.

ListDrivers

GET https://easyroutes.roundtrip.ai/api/2024-07/drivers

Fetch a list of all drivers associated with the shop. By default this returns all drivers but can optionally filter to specific statuses (i.e. ACTIVE, INACTIVE, or ARCHIVED). Invited drivers that are still pending sign-up are not returned by this API. 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/drivers

Query Parameters

Field Type Description
query.limit int32 Maximum number of drivers to return. Must be less than or equal to 200. Defaults to 20.
query.status DriverStatus[] Filter drivers by status. You can specify multiple statuses to filter by by repeating the query parameter, i.e. ?status=ACTIVE&status=INACTIVE.
cursor string Cursor to fetch the next page of results (if available). Should only be set on subsequent requests.

Response

Field Type Description
drivers Driver[] List of drivers.
nextCursor string Cursor to fetch the next page of results (if available).

GetDriver

GET https://easyroutes.roundtrip.ai/api/2024-07/drivers/{id}

Fetch a single driver 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/drivers/drv-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939

Path Parameters

Field Type Description
id string The ID of the driver to fetch.

Response

Driver

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 (e.g. "NY") as subdivision codes in ISO 3166-2 format without the country prefix (e.g. NY for New York).
countryCode string Country code (e.g. "US").
zip string Postal or ZIP code (e.g. "10001").

AttemptedReason

Value Description
UNKNOWN Unknown reason for marking stop as attempted.
NOT_AVAILABLE Reason for attempted was customer was not available.
ACCESS_DENIED Reason for attempted was Access denied.
INCORRECT_ADDRESS Reason for attempted was incorrect address.
SAFE_PLACE_UNAVAILABLE Reason for attempted was that no safe place to leave package(s).
REFUSED Reason for attempted was delivery refused.
EXTERNAL Reason for attempted was external factors (weather, traffic, etc.).
INCORRECT_ITEMS Reason for attempted was incorrect or missing item(s).
OTHER Reason for attempted was other.

Attribute

Field Type Description
key string Attribute key. Must be non-empty.
value string Attribute value.

BreakStatus

Value Description
UNKNOWN Unknown break status (not completed).
COMPLETED Break stop has been completed.

Contact

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 in E.164 format (e.g. "+14265551000").
email string Email address (e.g. "john.doe@roundtrip.ai")

Date

Field Type Description
year int32 Year of the date. Must be from 1 to 9999.
month int32 Month of a year. Must be from 1 to 12.
day int32 Day of a month. Must be from 1 to 31.

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").
phone string Driver phone number in E.164 format (e.g. "+14265551000").
status DriverStatus Shop driver status. (e.g. ACTIVE).

DriverStatus

Value Description
UNKNOWN Unknown driver status.
ACTIVE Driver is active.
INACTIVE Driver is deactivated.
ARCHIVED Driver is archived.

ImportedStop

Field Type Description
id string The ID of the imported stop, generated by EasyRoutes (e.g. "ist-123e4567-e89b-12d3-a456-426614174000").
clientStopId string The client-provided ID associated with the imported stop, if provided.
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.
timeWindows TimeWindow[] The time window for the stop. Note that we currently support at most one time window but may support multiple time windows in the future.
deliveryDate Date The delivery date for the stop.
attributes Attribute[] The additional key-value attributes set on the imported stop.
tags string[] The tags for the stop.
tasks TaskTemplate[] The tasks for the stop.
type StopType The type of stop (DELIVERY, PICKUP, or TASK). Defaults to DELIVERY if not provided.

ImportedStopRouteInfo

Field Type Description
routeId string The ID of the route the stop is associated with (e.g. "rte-123e4567-e89b-12d3-a456-426614174000").
stopId string The ID of the stop on the route (e.g. "rst-123e4567-e89b-12d3-a456-426614174000").
deliveryStatus DeliveryStatus The status for the stop on the route.

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.
totalDistanceMeters double The distance in meters for the entire route.
totalItemQuantity int32 The total quantity of items to deliver on the route.
totalItemGrams int64 (encoded as string) The total weight in grams for the items on the route.

RouteEnd

Field Type Description
address Address The end address of the route.
tasks Task[] Tasks to complete before finishing the route.
plannedArrival string (RFC3339 format) Planned arrival time at the end of the route.
distanceMeters double The distance in meters from the previous stop.
updatedArrival string (RFC3339 format) Estimated arrival time at the end of the route. If the route is completed, this will be the actual arrival time.
status RouteEndStatus Status indicating whether the route has been completed.

RouteEndStatus

Value Description
UNKNOWN Unknown route end status (not complete).
COMPLETED Route has completed.

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.
status RouteStartStatus Status indicating wheter the route has been started.

RouteStartStatus

Value Description
UNKNOWN Unknown route start status (not started).
STARTED Route has started.

RouteStop

Field Type Description
id string Stop ID (e.g. "rst-123e4567-e89b-12d3-a456-426614174000").
type StopType The type of stop (DELIVERY, BREAK, PICKUP, or TASK).
deliveryStatus DeliveryStatus The status for DELIVERY, PICKUP, or TASK 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 (encoded as string) 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.
orderName string The name of the order associated with the stop. For Shopify orders, the name is generated by combining the order_number property with the order prefix and suffix that are set in the merchant's general settings. For EasyRoutes imported orders, this field is populated with the order name provided on import.
distanceMeters double The distance in meters from the previous stop.
updatedArrival string (RFC3339 format) Estimated arrival time at the stop. If the stop is completed, this will be the actual arrival time.
timeWindows TimeWindow[] The time window for the stop. Note that we currently support at most one time window but may support multiple time windows in the future.
deliveryDate Date The planned delivery date for the stop.
attributes Attribute[] Additional attributes for the stop. Attributes are key-value pairs for storing additional structured data on stops. These may be populated from the Shopify order or set on import.
clientStopId string The client-provided ID associated with the stop, if provided on import.
tags string[] The tags for the stop. Tags are used to categorize stops and can be used for filtering and grouping stops in the EasyRoutes web app. These may be populated from the Shopify order or set on import.
attemptedReason AttemptedReason The reason for marking the stop as attempted. This is only populated when delivery_status = ATTEMPTED_DELIVERY.
attemptedNote string Optional note related to the reason for marking the stop as attempted. This is optionally populated when delivery_status = ATTEMPTED_DELIVERY.

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
clientStopId string Optional unique ID to associate with the imported stop. If provided, and a stop with the same client_stop_id already exists, the existing stop will be replaced with the new data. Otherwise, a new stop will be created. Note this ID is distinct from the EasyRoutes-generated stop id.
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.
timeWindows TimeWindow[] The time windows for the stop. Note that we currently support at most one time window but accept an array for future compatibility.
deliveryDate Date The delivery date for the stop.
attributes Attribute[] Additional attributes for the stop. Attributes are key-value pairs for storing additional structured data on stops. You may specify up to 50 attributes per stop.
tags string[] The tags for the stop. Tags are used to categorize stops and can be used for filtering and grouping stops in the EasyRoutes web app. You may specify up to 250 tags per stop.
tasks TaskTemplate[] The tasks for the stop. Tasks are used to define the work that needs to be completed at the stop by the driver, when the stop is added to a route.
type StopType The type of stop (DELIVERY, PICKUP, or TASK). Defaults to DELIVERY if not provided.

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 completed. 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.

TaskInput

Field Type Description
value string Input value.
updatedAt string (RFC3339 format) Timestamp when the input was last updated.
inputMethod TaskInputMethod Whether input was scanned (e.g. a scanned barcode)

TaskInputMethod

Value Description
UNKNOWN Unknown input method (e.g. manually entered in the system).
SCANNED Input was scanned in the app.

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.

TaskItemTemplate

Field Type Description
title string Item title (e.g. "Pick up package").

TaskTemplate

Field Type Description
title string Task title (e.g. "Delivery checklist").
type TaskType Task type.
items TaskItemTemplate[] Task items, which are required for CHECKBOXES and RADIO_BUTTONS).
requiredToMarkStopAsDelivered bool Whether the task is required to mark the stop as completed.
requiredToMarkStopAsAttempted bool Whether the task is required to mark the stop as attempted.

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.
SCANNER_INPUT Task with scanner input.

TimeOfDay

Field Type Description
hours int32 Hours of day in 24 hour format. Should be from 0 to 23.
minutes int32 Minutes of hour of day. Must be from 0 to 59.
seconds int32 Seconds of minutes of the time. Must be from 0 to 59.

TimeWindow

Field Type Description
start TimeOfDay The start time of the time window (optional).
end TimeOfDay The end time of the time window (optional).
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles