SmartRoutes API

Fires when an order's status changes (line-item or order-level transition).

Type ID: 2.

Fires when a Plan row is persisted — after POST /plans/optimise/orders or POST /plans/optimise/orders-for-ids.

It fires before optimisation completes, so a delivery does not mean the optimisation finished — poll GET /plans/{id} for the outcome. See Optimise Orders.

Type ID: 4.

Fires when a Plan is dispatched (routes published to drivers).

Type ID: 5.

Fires when a dispatched route is edited (re-ordering stops, etc.).

Type ID: 6.

Fires when one or more dispatched routes are deleted (typically as part of solution replacement), once per deleted route.

Type ID: 7.

Fires when a dispatched route is completed by the driver.

Type ID: 8.

Fires when a Plan row is destroyed.

Type ID: 9.

Fires when a stop enters its on-delivery ETA window on a dispatched route (the arriving-soon signal). Rides on the depot's on-delivery customer notifications — fires once per stop, and only for stops that carry contact details.

Type ID: 10.

Checks whether one more order could be fitted in on a given date before you accept the booking. Nothing is created or reserved, and the response is just {"booking": {"available": true|false}}.

Availability is worked out by running the routing engine on the spot. It takes every order already scheduled for date in this depot, adds the order you describe, and plans the whole day from scratch on either the vehicles you list in vehicles or, if you leave that out, all active vehicles. available is true only if every stop, both the existing ones and the new one, fits into a route. Your existing plans and routes for that day are not used. So a day that is already overbooked returns false even when the new order itself would fit.

• The order's location comes from delivery_* fields for delivery orders and from pickup_* fields otherwise. If you don't send both lat and lng, the address and postcode are geocoded first. If geocoding fails you get 400 GEOCODING_FAILED.
• Capacity ids that don't belong to the depot are ignored, and so are vehicle ids that don't belong to it. Look up valid capacity ids with GET /capacities.
• If any vehicle used for the check has no shift on that weekday, the request fails with 400 INVALID_INPUT.

The call waits for the routing engine to finish, so it is much slower than a normal read. It also has a stricter rate limit of 5 / min (see Rate Limits), so call it when a customer is booking, not in bulk.

Lists the capacity types (for example pallets, weight or volume) set up for the depot your API key belongs to. Use it to look up the capacity ids that orders, customers, vehicles and POST /booking/availability accept in their capacities arrays.

Each entry has id, type (the display name), default (the default amount for that capacity type), created and updated. Deleted capacity types are left out. The list covers this depot only and is returned in full, with no paging.

Lists the custom fields set up for the depot your API key belongs to. Use it to look up the ids and names you send in custom_fields on POST /orders, PUT /orders/{id}, POST /customers and PUT /customers/{id}.

Each entry has id, name, created and updated. Deleted fields are left out. The list covers this depot only and is returned in full, with no paging. When you create orders, a custom field that matches neither an id nor a name here is silently skipped, so check against this list if values seem to go missing.

Lists the customers in your depot, most recently updated first. Each item carries the customer's core details (id, account, name, address, lat/lng, phone, email, duration, notes, created, updated). Capacities, skills, tags, time windows and custom fields are not included; fetch them per customer with GET /customers/{id}.

Results are paged. limit sets the page size (1–100, default 100), and the Link header holds the URL of the next page. See Paging. updated_at_min (YYYY-MM-DD hh:mm:ss or YYYY-MM-DDTHH:mm:ss.SSSZ) returns only customers updated after that time. A limit outside 1–100 falls back to 100, and an updated_at_min in any other format is ignored rather than rejected. A malformed page_info returns 400 INVALID_INPUT.

Creates or updates up to 100 customers in your depot in one request, matching on account. If a customer with that account already exists in your depot, it is updated: the fields you send overwrite the stored values, and the fields you leave out are kept. For capacities, skills, tags, time_windows and custom_fields, sending the array replaces the customer's whole set (an empty array clears it). Leaving the array out keeps the existing set.

• Each customer needs an address, or both lat and lng. An address sent without coordinates is geocoded. If geocoding fails, the customer is still saved, just without coordinates.
• capacities are matched by id (see GET /capacities), skills and tags by name (ignoring case), and custom_fields by id or name (see GET /custom-fields). Entries that match nothing in your depot or organisation are dropped without an error.
• If any customer in the array fails validation, nothing is saved and the response is 400 INVALID_INPUT. A depot can hold at most 300,000 customers. A request that would go over that limit is also rejected with 400 INVALID_INPUT.

The response lists the id and account of each customer, in request order. This endpoint supports Idempotency, but a replayed response has the original status and an empty body, so recover the IDs with GET /customers. Because customers are matched on account, sending the same batch again updates the same customers rather than creating duplicates.

Returns one customer from your depot by its SmartRoutes id, nested under a customer key. The response includes the customer's details plus its capacities, skills, tags, time windows and custom fields. If you only have the account reference, find the customer with GET /customers first. An id that doesn't exist in your depot returns 404 RESOURCE_NOT_FOUND.

Updates one customer in your depot. This is a partial update: only the fields you send change. For capacities, skills, tags, time_windows and custom_fields, sending the array replaces the customer's whole set (an empty array clears it), and leaving it out keeps the existing set. Capacities, skills and tags that don't exist in your depot or organisation are dropped without an error. Custom fields are matched by id only.

• Every request must include either address or both lat and lng, even when you are only changing other fields.
• Changing address without sending coordinates re-geocodes the customer. If geocoding fails, the update is still saved and the failure is reported as a GEOCODING_FAILED entry in the response's errors array.
• Setting account to a value another customer in your depot already uses returns 400 INVALID_INPUT.

The response holds the updated customer under customer (the same shape as GET /customers/{id}) along with an errors array.

Retrieve a driver questionnaire submission and its answers by submission ID.

Each answer carries an images array of absolute URLs pointing at GET /driver-questionnaire-images/{id}. Only images the driver app has finished uploading are listed. Images are compressed asynchronously after upload, so a URL taken from this response may answer 202 Accepted with a Retry-After header instead of image data if it is followed before compression finishes — apply the same retry logic described on that endpoint.

Retrieve a driver questionnaire image (photo or signature) by its ID. The IDs come from the images arrays on GET /driver-questionnaire-submission/{id}. By default returns the raw image binary. Use the encoding query parameter to request a Base64-encoded JSON response instead.

Images are compressed asynchronously after the driver uploads them. If the image exists but compression has not finished, this endpoint returns 202 Accepted with a Retry-After header and the image's model (id and is_compressed: false) as the JSON body, instead of image data — retry after the interval given. Image data is returned as WebP; the Content-Type header (or content_type in the Base64 response) states the format.

Lists the SMS and email notifications scheduled for the depot your API key belongs to, with their recipient, rendered message, scheduled send time and status. Use it to check what was queued by POST /notifications/schedule/orders or by your notification automations, and whether it has been sent.

Results are paged, most recently updated first. Use limit (up to 100) and follow the Link header for the next page (see Paging). Filters:

• updated_at_min returns only tasks updated at or after the given time.
• status matches the task status exactly, for example Scheduled or Cancelled.
• type is SMS or EMAIL (case-insensitive). Any other value returns 400 INVALID_INPUT.

Each task links to the order or visit it was created for, and the other one is null. The template gives the id of the template that was used (see GET /notifications/templates).

Lists the SMS and email notification templates set up for the depot your API key belongs to. Use it to look up the template ids you pass in templates to POST /notifications/schedule/orders.

The response is a plain JSON array, not wrapped in a key. Each entry has id, type (SMS or EMAIL) and name. Deleted templates are left out, and the list is returned in full, with no paging. Templates are created and edited in the SmartRoutes web app, not through the API.

Schedules SMS and/or email notifications to the customers on a set of orders, using up to two of your notification templates (see GET /notifications/templates). One notification is created for each order and template pair. It is sent at send_time_utc, or straight away if you leave that out.

• The recipient is the order's contact phone number or email. If the order has none, the linked customer's phone number or email is used.
• Each SMS uses one credit per 160 characters of the rendered message, and the credits are deducted when the notification is scheduled. If the depot has no SMS credits left, SMS templates are skipped without being reported in errors.
• Order and template ids that don't belong to this depot are ignored. If none of the orders are found, the response is 404 RESOURCE_NOT_FOUND.
• Nothing checks for duplicates. Calling again for the same orders schedules the notifications again.

The request can partly succeed. The response is 200 with notifications listing the order_id of each notification created, and errors listing each order and template pair that was skipped and why (for example, no phone number, or an invalid email). Check errors even when the status is 200. To see the scheduled notifications, use GET /notification-tasks. Supports the idempotency-key header, so a retry won't schedule twice (see Idempotency).

Every order status your organisation can use: the SmartRoutes defaults that every organisation has, plus any custom statuses your organisation has added.

Order statuses are organisation-wide — the same list is returned for every depot in your organisation, and it is the same list your users see in the SmartRoutes web app.

Aggregate PARTIALLY_* statuses are excluded: SmartRoutes derives those from line-item states and they are never chosen directly.

Add a status to your organisation's catalogue. The status becomes available to every depot in your organisation and appears in the SmartRoutes web app.

The name is stored as you send it — surrounding whitespace is not trimmed. The response carries the name exactly as it will appear on orders; use that value when removing it later.

Adding a name your organisation already has, or one of the SmartRoutes defaults, returns 400.

Remove a custom status from your organisation's catalogue.

This only removes the status from your organisation's list. Orders already carrying the status keep it — their status is not rewritten, and GET /orders will still return it.

Removing a SmartRoutes default returns 400. A name your organisation has not added returns 404.

Create or update up to 100 orders in your depot in one request. Orders are matched on order_number. A new number creates an order. A number that already exists in your depot updates that order instead of creating a duplicate, and restores it if it was deleted. Send each order complete, because some fields you leave out are reset rather than kept. To change only some fields of an existing order, use PUT /orders/{id}.

The whole batch is checked before anything is saved, and any problem rejects all of it with 400 INVALID_INPUT. This includes:

• more than 100 orders, or the same order_number twice in one request
• an order with no address for its type (shipment needs both)
• a skill, vehicle or third party that doesn't exist
• an order_exchange.reference that isn't shared by exactly two orders

If your depot doesn't allow orders without customers, any order without a customer is rejected with 403 PERMISSION. Custom fields, capacities and tags that don't exist in your depot are skipped silently, not rejected.

Addresses sent without coordinates are geocoded. A geocoding failure doesn't fail the request. The order is still saved, and the failure is listed in errors with name GEOCODING_FAILED and the order's order_number. The response gives the id and order_number of every order you sent. Fetch any of them in full with GET /orders/{id}. New orders start as OPEN, or as your depot's configured starting status. Existing orders keep their current status.

Supports Idempotency: retrying with the same idempotency-key returns the original response without processing the orders again.