Jobs
The work drivers carry out for each order, one day at a time.
A job is one visit: a delivery, a collection (pickup), an exchange (changeover), a service
visit or a one-off task. An order produces the jobs it needs, and each job points back to it with
orderId and orderReference.
Status
status |
Meaning |
|---|---|
booked |
Scheduled, with no driver yet. |
allocated |
A driver is assigned. driverId says who. |
done |
Completed. completedAt says when. |
cancelled |
Will not happen, usually because the order was cancelled. |
startedAt is set when the driver starts the job and heads to the site. A driver who cannot
complete a job records a failed attempt, and the job stays open to be rescheduled.
Reading a day
GET /api/v1/jobs?date=YYYY-MM-DD returns every job scheduled on that date in one response. The date
is in the organisation's timezone. To follow jobs through the day without polling, subscribe to the
job.started, job.completed and job.failed webhooks.
GET/api/v1/jobs
Every job scheduled on one date: deliveries, collections, exchanges and services, with their status.
- Beta — still moving. Changes are announced in the changelog before they ship.
- Needs an API key. Call it from your server, never a browser.
- Works with read-only and read and write keys.
Query parameters
| Name | Required | Description |
|---|---|---|
date | Yes | `YYYY-MM-DD`, in the organisation's timezone. |
Headers
| Name | Required | Description |
|---|---|---|
Authorization | Yes | Your API key as a bearer token: `Bearer ops25_sk_…`. |
Errors
| Status | When |
|---|---|
401 | The key is missing, malformed or revoked. |
429 | More than 600 requests from this key in a minute. |
422 | `date` is missing or not a date. |
GET/api/v1/jobs/{id}
One job, by its id.
- Beta — still moving. Changes are announced in the changelog before they ship.
- Needs an API key. Call it from your server, never a browser.
- Works with read-only and read and write keys.
Path parameters
| Name | Description |
|---|---|
id | The job id, a UUID. |
Headers
| Name | Required | Description |
|---|---|---|
Authorization | Yes | Your API key as a bearer token: `Bearer ops25_sk_…`. |
Errors
| Status | When |
|---|---|
401 | The key is missing, malformed or revoked. |
429 | More than 600 requests from this key in a minute. |
404 | No job in this organisation has that id. |