EasyRoutes API - Developer Overview

EasyRoutes is a route optimization and delivery management platform for last-mile delivery, built for e-commerce businesses. The API lets you integrate EasyRoutes with your existing systems — import orders, read route data, and react to delivery events in real-time.

What you can do

Note: Optimized route creation happen in the EasyRoutes app (manually or automated via our Workflows). The API focuses on updating planned routes, importing stops and reading data.

Core concepts

Routes

A planned sequence of stops for a driver on a given day. Includes start/end locations, assigned driver, and optimization status.

ID format: rte-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx     

Route Stops

Individual deliveries on a route. Contains address, customer info, delivery status, and proof of delivery (photos, signature, notes).

ID format: rst-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx     

Imported Stops

Orders you've sent to EasyRoutes via API that haven't been added to a route yet. They appear in your Orders page, ready for route planning.

ID format: ist-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx     

Drivers

Team members who deliver routes. Includes contact info and current status.

ID format: drv-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx     

Webhooks

Real-time notifications when things happen — routes dispatched, stops delivered, drivers updated. Register webhooks in Settings > API.

Authentication

1. Get your Client ID and Secret from Settings > API
2. Exchange them for an access token via POST /authenticate     
3. Include the token in all requests: Authorization: Bearer {token}     

Tokens expire after 1 hour. See the Getting Started Guide for details.

Base URL

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

Common workflows

Import orders from your system

1. Authenticate
2. POST /stops/imports      with your order data
3. Stops appear in EasyRoutes Orders page
4. Add to routes via our endpoint or let Workflows assign them automatically on route creation

Sync delivery status to your system

1. Register a webhook for STOP_STATUS_UPDATED     
2. When a stop is delivered, you receive the event
3. Update your order management system

Track proof of delivery

1. Subscribe to STOP_UPDATED      webhook
2. Access photos, signatures, and notes from the payload
3. Store or display in your system

Best Practices

Consider the following when building solutions or integrations with the EasyRoutes API.

Security

• Store credentials securely: Never commit API keys to version control
• Use HTTPS: All API requests must use HTTPS
• Rotate tokens: Implement token refresh logic before expiration (tokens expire after 1 hour)
• Validate webhooks: Verify webhook signatures using HMAC-SHA256 (sent in X-EasyRoutes-Hmac-Sha256    header)

Performance

• Cache access tokens: Reuse tokens until they expire (1 hour)
• Batch operations: Import or add multiple stops in a single request when possible
• Use webhooks: Prefer event-driven updates over polling
• Implement pagination: Don't request all records at once

Reliability

• Idempotent imports: Use client_stop_id    when importing stops - existing stops with the same ID will be replaced instead of duplicated
• Retry logic: Implement retries with exponential backoff for transient errors
• Monitor webhooks: Track webhook delivery success and implement retry logic for failed deliveries
• Validate inputs: Check data constraints before sending requests
• Log requests: Maintain request/response logs for debugging

Data Quality

• Geocode addresses: Ensure addresses on your stops have valid addresses that can be matched to a geolocation.
• Structured phone numbers: When inputting phone numbers, ensure these are in the expected E.164 format.
• Use custom IDs: Include your order IDs in the client_stop_id    field for reference and idempotent updates
• Add metadata: Use tags and attributes for filtering and reporting, add a delivery date or time window if these are constraints required for planning routes, etc.

Data formats

Timestamps: RFC3339 with timezone — "2024-12-15T14:30:00Z"     

Durations: Seconds as string — "300s"      (5 minutes)

Coordinates:

{ "latitude": 43.6532, "longitude": -79.3832 }

Addresses:

{
  "address1": "123 Queen St W",
  "city": "Toronto",
  "provinceCode": "ON",
  "countryCode": "CA",
  "zip": "M5H 2M9"
}

Error handling

Error responses include a message      field explaining what went wrong.

Pagination

List endpoints return up to 20 items by default. Use cursor-based pagination for more:

GET /routes?limit=20&cursor=eyJsYXN0X2lkIjoiMTIzIn0=

Response includes nextCursor      — pass it in subsequent requests.

Next steps