Tracking

There are three ways to follow a delivery, and most integrations use more than one:

Webhooks tell you when something changes — see Webhooks.
Reading the job tells you what is true now, whenever you ask.
The tracking link is a public page for your customer.

Reading a job

GET /v1/jobs/{id}

Everything the booking returned, plus what has happened since:

{
  "id": "0199d2c5-1f3a-7d10-8b2e-6c4a9e0f2d31",
  "reference": "JOB-7F3K2Q",
  "status": "in_transit",
  "currency": "GBP",
  "price_amount_minor": 918,
  "tax_amount_minor": 153,
  "vehicle": "bicycle",
  "tracking_url": "https://track.courier.example/4mZ8qPx2",
  "pickup":  { "latitude": 51.508, "longitude": -0.1281, "address": "Trafalgar Square, London", "postcode": null, "contact_name": "The kitchen", "contact_phone": "+44 20 7946 0100", "notes": "Ask at the counter." },
  "dropoff": { "latitude": 51.5081, "longitude": -0.0759, "address": "Tower Hill, London", "postcode": null, "contact_name": "Alex Rivera", "contact_phone": "+44 7700 900456", "notes": "Second floor, buzzer 4." },
  "booked_at": "2026-10-10T12:04:31+00:00",
  "scheduled_for": null,
  "assigned_at": "2026-10-10T12:05:02+00:00",
  "completed_at": null,
  "cancellation_reason": null,
  "items": [{ "name": "Margherita", "unit_price_minor": 900, "quantity": 2, "line_total_minor": 1800 }],
  "items_subtotal_minor": 1800,
  "discount_minor": 0,
  "items_total_minor": 1800,
  "proof_requirement": { "photo_required": true, "signature_required": false },
  "proof": null,
  "notify_customer": true,
  "customer_notified_at": "2026-10-10T12:18:40+00:00"
}

cancellation_reason is filled in when the job was cancelled.
proof appears once the job ends at the door — see Proof of delivery.
customer_notified_at says when the customer was texted the tracking link, if they were.

A job that isn’t yours is 404 Not Found — the same answer as one that doesn’t exist. The courier’s name and phone number are deliberately not part of the job: the tracking link is the way to follow a courier.

Listing your jobs

GET /v1/jobs?status=delivered,returned&from=2026-10-10T00:00:00Z&page=1&size=50

Your own deliveries, newest first, a page at a time.

Parameter
`status`	One status or several, comma-separated. An unknown status is refused with `request.unknown_status` rather than ignored.
`from`, `to`	Booked at or after, and before. ISO 8601.
`page`	From `1`.
`size`	Up to `200`. Default `50`.

{
  "items": [
    {
      "id": "0199d2c5-1f3a-7d10-8b2e-6c4a9e0f2d31",
      "reference": "JOB-7F3K2Q",
      "status": "delivered",
      "currency": "GBP",
      "price_amount_minor": 918,
      "vehicle": "bicycle",
      "pickup_address": "Trafalgar Square, London",
      "dropoff_address": "Tower Hill, London",
      "booked_at": "2026-10-10T12:04:31+00:00",
      "scheduled_for": null,
      "assigned_at": "2026-10-10T12:05:02+00:00",
      "completed_at": "2026-10-10T12:31:04+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50
}

The list leaves out contact names and phone numbers on purpose. Read a single job for those.

Where the courier is

GET /v1/jobs/{id}/courier-position

{ "latitude": 51.5112, "longitude": -0.0921, "seen_at": "2026-10-10T12:24:10+00:00" }

204 No Content means there is nothing to draw: nobody is on the job yet, or the courier hasn’t been heard from lately. Always show seen_at with the pin — a position is a fact about a moment.

The tracking link

tracking_url on every job is a public page showing the delivery’s progress, the route and where the courier was last seen. It needs no sign-in, so it’s safe to put in your own emails and order pages. If texting is on, the customer receives the same link by text when the courier collects.