Introduction

The SmartRoutes Open API allows you to use the power of the SmartRoutes Routing Engine directly from within your own software application.

To use the API, you will need to generate an API Access Key for your SmartRoutes account. To generate, login to your SmartRoutes account and navigate to Settings > Integrations > SmartRoutes Open API and click 'Generate API Key'. For more details on SmartRoutes integrations, click here.

This access key can be used to connect to the API.

Webhooks

Configure a webhook receiver URL in your depot settings and SmartRoutes will deliver event notifications as they happen. Seven event types are emitted:

Event	Type ID	Fires when	data payload
ORDERS_STATUS	2	An order's status changes (line-item or order-level transition)	{ "order_id": <int>, "order_number": <string>, "status": <OrderStatus> }
PLANS_CREATED	4	A Plan row is persisted (after POST /plans/optimise/orders or /orders-for-ids). Fires before optimisation completes — see the optimise endpoint description.	{ "id": <int> } — plan id
PLANS_DISPATCHED	5	A Plan is dispatched (routes published to drivers).	{ "id": <int> } — plan id
ROUTES_EDITED	6	A dispatched route is edited (re-ordering stops, etc.)	{ "id": <int> } — route id
ROUTES_DELETED	7	One or more dispatched routes are deleted (typically as part of solution replacement)	{ "id": <int> } — route id
ROUTES_COMPLETED	8	A dispatched route is completed by the driver.	{ "id": <int> } — route id
PLANS_DELETED	9	A Plan row is destroyed	{ "id": <int> } — plan id

Delivery envelope

Each event is delivered as an HTTP POST to the receiver URL configured in your depot settings. The request body is always a JSON object of shape:

{ "type": <event type string from the table above>, "data": <payload object from the table above> }

The data field is the payload object for a single event — NOT an array. Bulk operations (e.g. order-status changes from a route delete) fan out into one POST per event, each with its own data object.

Headers

Outgoing requests carry Content-Type: application/json and an HTTP Basic Authorization header derived from the username/password you supplied when configuring the webhook. No HMAC signature header is sent; treat the basic-auth credentials as the integrity check and rotate them if compromised.

Timeout and retries

Each delivery has a server-side request timeout of 3 seconds. On failure (HTTP error, timeout, or connection error) the delivery is retried up to 3 times total; after the third failure the task is marked permanently ERROR and not retried again. Your receiver should respond 2xx quickly — slow receivers will be treated as failures.

Machine-readable schemas

The delivery envelope and per-event payloads are also defined under #/components/schemas/: WebhookDelivery, WebhookOrdersStatusPayload, WebhookPlanIdPayload, WebhookRouteIdPayload. Reference these from your own integration's tests / contract tools to catch shape drift early.

Headers

All requests expect the API Access key to be provided in a header x-access-key:YOUR_ACCESS_KEY

Rate Limits

Every endpoint has a per-minute limit, and most also have a short burst limit. Requests are rejected as soon as either limit is hit.

Most endpoints fall into one of these tiers:

Tier	Rate limit	Description
Standard	60 / min (max 5 / sec)	Single-resource reads and writes (e.g. GET /orders/{id}, PUT /orders/{id})
Listing	30 / min (max 5 / sec)	Paginated lists (e.g. /customers, /plans, /routes)
Reference	60 / min (max 1 / sec)	Reference data (e.g. depots, capacities, custom fields, vehicles, zone groups)
Bulk	30 / min (max 1 per 2 sec)	Bulk creates and heavy deletes
Upload	15 / min (max 1 / sec)	File uploads (e.g. POST /orders/{id}/attachments)

The following endpoints have a stricter limit of 5 / min (max 2 per 15 sec):

• Plan optimisation: POST /plans/optimise/orders, POST /plans/optimise/orders-for-ids
• Booking availability: POST /booking/availability, POST /booking/available-dates, POST /booking/available-slots
• Route reversal: POST /routes/{id}/reverse

When a limit is hit, the API returns HTTP 403 with a Retry-After header and details.retry_after_seconds in the body — both give the seconds until the limit resets.

We may temporarily reduce these limits to protect platform stability. We aim to keep such reductions brief and rare. However, your application should be built to handle rate limits gracefully.

Idempotency

State-changing POST endpoints accept an optional idempotency-key request header. The mechanism is Stripe-style: send the same key with a retry of the same request and the server returns the original response without re-executing the underlying operation.

Header: idempotency-key: <opaque string, 1–255 characters>. The key can be any client-chosen identifier — a UUID is recommended. Keys are scoped per (api-key, endpoint), so the same key on two different endpoints is treated as two distinct operations.

Retention: 24 hours from the time the original request was received.

Behaviour:

• Replay (same key, same body, completed) — server returns the original status code and response body. The response header idempotency-replay: true indicates the response is a cached replay. The underlying operation is not re-executed. Replays do not consume rate-limit or data-row quota.
• Body mismatch (same key, different body) — server returns 422 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY.
• In-flight (same key, original request still processing) — server returns 409 IDEMPOTENCY_REQUEST_IN_PROGRESS with a Retry-After header. Retry after the period given.
• 5xx server error — the cached reservation is released. A retry with the same key is treated as a fresh request and can re-execute. 4xx client errors are cached: replays return the same 4xx response.
• Invalid key (empty, or longer than 255 chars) — server returns 400 IDEMPOTENCY_INVALID_KEY.

Supporting endpoints (Phase 1):

• POST /orders
• POST /depots/{id}/orders
• POST /plans/optimise/orders
• POST /plans/optimise/orders-for-ids
• POST /customers/
• POST /vehicles/
• POST /notifications/schedule/orders

Other POST endpoints ignore the header. Multipart uploads (POST /orders/{id}/attachments) are excluded from idempotency in this phase.

Paging

Usage:

Make an initial request to the API endpoint with the desired query parameters. The API response includes the requested data and a Link header for the next page. Use the URL provided in the Link header to make subsequent requests for the next page.

Example: "<https://api.smartroutes.io/v2/orders?page_info=PAGE_INFO_STRING&limit=100>; rel=next"

Query Parameters

limit: Specifies the maximum number of items per page. Limited to a maximum of 100

Example: limit=50

updated_at_min: Filters results based on the minimum update timestamp in the format YYYY-MM-DD hh:mm:ss or YYYY-MM-DDTHH:mm:ss.SSSZ.

Example: updated_at_min=2023-01-01 12:00:00 OR updated_at_min=2023-01-01T12:00:00.000Z

status: Filters results based on the order status.

Example: status=Pending

Error Responses

Errors are classified into specific types, each identified by a unique name and accompanied by an appropriate HTTP statusCode. The error responses include a brief description of the error, and additional details that provide more context about the specific issue.

Error Types

RESOURCE_NOT_FOUND - statusCode: 404 - description: The requested resource could not be found.

INVALID_INPUT

• statusCode: 400
• description: The submitted input data is invalid.
• details: An object { validationErrors: An array of Zod errors specifying validation issues in the submitted data. } containing additional details about the error. For processing validation errors, refer to Zod Documentation .

GEOCODING_FAILED

• statusCode: 500
• description: Geocoding operation failed.
• details: An object containing additional details about the error.