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.

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 (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.
totalDistanceMeters double The distance in meters for the entire 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.

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

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.

TaskInput

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.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles