Skip to main content

Status types

Each webhook's status field identifies the message type and determines which extra fields are present, on top of the common envelope (job, account, dates, partner_reference).

Lifecycle​

A typical booking flows through these states:

BOOKED → ALLOCATED / UNALLOCATED
         ↓
       ONWAY → ARRIVED → ONBOARD → DONE
                                    ↓
                               PRICED / PAYMENT_UPDATE
                                    ↓
                               COMPLETED → PAID

CANCELLED  — can occur at any stage
TRACKING   — driver location updates, independent of the booking flow

Status reference​

StatusMeaningNotable extra fields
BOOKEDThe booking has been confirmed.Common envelope only.
ALLOCATEDA driver and vehicle have been assigned.allocation (driver + vehicle).
UNALLOCATEDA previously assigned driver/vehicle was removed.Common envelope only.
ONWAYThe driver is on the way to a stop.allocation (with driver geo), stop_number, locations.
ARRIVEDThe driver has arrived at a stop and is waiting.allocation, stop_number.
ONBOARDThe passenger(s) have boarded; the trip is underway.allocation, stop_number.
DONEThe driver has completed a stop or the final leg.allocation, stop_number.
PRICEDThe job has been priced (typically after completion).pricing, taxes, distance, journey.
COMPLETEDThe job is fully completed and signed off.pricing, taxes, distance, journey, signatures.
PAIDPayment for the job has been collected.pricing, taxes, distance, journey.
PAYMENT_UPDATEPricing/payment details were revised after PRICED/PAID.Same as PAID.
CANCELLEDThe booking was cancelled.reasons.cancel; job.cancelled_on_arrival / cancelled_by.
TRACKINGReal-time driver location ping.allocation, geo (with speed/bearing), heading (ETA).

Allocation, pricing, and tracking​

  • allocation identifies the resource assigned to the job. Its type is DRIVER or COURIER, and it carries the driver and vehicle details. From ONWAY onward the driver includes a live geo position.
  • pricing (on PRICED/COMPLETED/PAID/PAYMENT_UPDATE) gives the net, tax, and total, plus a prices breakdown of line items (mileage, waiting time, surcharges) and a taxes array. journey lists the stops actually visited.
  • TRACKING carries the driver's current geo (with speed and bearing) and a heading block with the destination address and ETA estimates. These arrive frequently — see the delivery notes in Overview.

Example payloads​

A representative body for each status is shown below. The same examples are available as a selectable dropdown on the bookingStatusUpdate webhook in the Webhooks reference.

BOOKED​

{
  "status": "BOOKED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7",
    "integration_uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7",
    "vendor": "J000000000000000000",
    "pickup_dt": "2026-07-09T00:15:00.000Z",
    "asap": false,
    "service": "standard_car",
    "as_directed": false,
    "cancelled_on_arrival": false
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-08T18:22:42.451+01:00",
    "sent": "2026-07-08T18:22:42.546+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60",
      "number": "9967230:J00000000"
    }
  }
}

ALLOCATED​

{
  "status": "ALLOCATED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7",
    "service": "standard_car"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:00:00.000+01:00",
    "sent": "2026-07-09T01:00:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60",
      "number": "9967230:J00000000"
    }
  },
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "license": "000000",
      "contact": "07000000000"
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  }
}

UNALLOCATED​

Same envelope as ALLOCATED but with no allocation — the previously assigned resource has been removed and the job is awaiting re-allocation.

{
  "status": "UNALLOCATED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:03:00.000+01:00",
    "sent": "2026-07-09T01:03:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  }
}

ONWAY​

{
  "status": "ONWAY",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7",
    "service": "standard_car"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:02:02.974+01:00",
    "sent": "2026-07-09T01:02:03.012+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60",
      "number": "9967230:J00000000"
    }
  },
  "stop_number": 1,
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "contact": "07000000000",
      "geo": {
        "lat": 51.472198,
        "long": -0.125747,
        "time": "2026-07-09T01:01:52.330+01:00",
        "bearing": 354
      }
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  }
}

ARRIVED​

{
  "status": "ARRIVED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:12:00.000+01:00",
    "sent": "2026-07-09T01:12:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  },
  "stop_number": 1,
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "contact": "07000000000"
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  }
}

ONBOARD​

{
  "status": "ONBOARD",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:15:00.000+01:00",
    "sent": "2026-07-09T01:15:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  },
  "stop_number": 1,
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "contact": "07000000000"
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  }
}

DONE​

{
  "status": "DONE",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T02:05:00.000+01:00",
    "sent": "2026-07-09T02:05:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  },
  "stop_number": 2,
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "contact": "07000000000"
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  }
}

PRICED​

Carries the pricing breakdown and journey itinerary — the same structure as COMPLETED below, but without signatures.

{
  "status": "PRICED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T03:15:00.000+01:00",
    "sent": "2026-07-09T03:15:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  },
  "pricing": {
    "currency_code": "GBP",
    "net": "115.52",
    "tax": "28.88",
    "total": "144.40",
    "prices": [
      {
        "name": "Journey Mileage",
        "type": "BASE",
        "tax": "01",
        "amount": 50.0,
        "rate": 2.74,
        "unit": "miles",
        "charge": "136.90"
      },
      {
        "name": "Waiting Time",
        "type": "WAIT",
        "tax": "01",
        "amount": 2,
        "rate": 3.0,
        "unit": "minutes",
        "charge": "6.00"
      }
    ]
  },
  "taxes": [
    {
      "name": "01",
      "description": "Value-Added Tax",
      "rate": 20.0,
      "unit": "percent",
      "net": "144.40",
      "charge": "28.88"
    }
  ],
  "distance": 83390.82
}

COMPLETED​

{
  "status": "COMPLETED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7",
    "pickup_dt": "2026-07-09T00:45:00.000Z",
    "asap": false,
    "service": "standard_car"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T03:17:52.341+01:00",
    "sent": "2026-07-09T03:17:52.456+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60",
      "number": "9967230:J00000000"
    }
  },
  "pricing": {
    "currency_code": "GBP",
    "net": "115.52",
    "tax": "28.88",
    "total": "144.40",
    "prices": [
      {
        "name": "Journey Mileage",
        "type": "BASE",
        "tax": "01",
        "amount": 50.0,
        "rate": 2.74,
        "unit": "miles",
        "charge": "136.90"
      },
      {
        "name": "Waiting Time",
        "type": "WAIT",
        "tax": "01",
        "amount": 2,
        "rate": 3.0,
        "unit": "minutes",
        "charge": "6.00"
      },
      {
        "name": "Greener Future Payment",
        "type": "GFP",
        "tax": "01",
        "amount": 1,
        "rate": 1.5,
        "unit": "fixed",
        "charge": "1.50"
      }
    ]
  },
  "taxes": [
    {
      "name": "01",
      "description": "Value-Added Tax",
      "rate": 20.0,
      "unit": "percent",
      "net": "144.40",
      "charge": "28.88"
    }
  ],
  "distance": 83390.82,
  "journey": [
    {
      "stop": {
        "type": "ADDRESS",
        "wait": 24,
        "address": {
          "formatted_address": "Euston Station, Melton Street, London, NW1 2EP",
          "address_components": {
            "locality": "London",
            "postal_code": "NW1 2EP",
            "country": "GB"
          }
        },
        "geo": {
          "lat": 51.526974,
          "long": -0.133928
        }
      }
    },
    {
      "stop": {
        "type": "ADDRESS",
        "wait": 0,
        "address": {
          "formatted_address": "5 Butterfield Close, Woolstone, MILTON KEYNES, MK15 0BZ",
          "address_components": {
            "locality": "MILTON KEYNES",
            "postal_code": "MK15 0BZ",
            "country": "GB"
          }
        },
        "geo": {
          "lat": 52.03962,
          "long": -0.728184
        }
      }
    }
  ]
}

Same shape as PRICED (pricing, taxes, distance, journey). PAYMENT_UPDATE is sent when the pricing is revised after an initial PRICED/PAID message.

{
  "status": "PAID",
  "job": {
    "id": "J000000000000000000",
    "number": 660531,
    "uuid": "d65bc9a2-9e01-451c-a483-12b208127fe7"
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T04:00:00.000+01:00",
    "sent": "2026-07-09T04:00:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60"
    }
  },
  "pricing": {
    "currency_code": "GBP",
    "net": "115.52",
    "tax": "28.88",
    "total": "144.40",
    "prices": []
  },
  "taxes": [
    {
      "name": "01",
      "description": "Value-Added Tax",
      "rate": 20.0,
      "unit": "percent",
      "net": "144.40",
      "charge": "28.88"
    }
  ],
  "distance": 83390.82
}

CANCELLED​

{
  "status": "CANCELLED",
  "job": {
    "id": "J000000000000000000",
    "number": 660531
  },
  "account": {
    "number": 100000
  },
  "dates": {
    "event": "2026-07-09T01:57:00.000+01:00",
    "sent": "2026-07-09T01:57:00.100+01:00"
  },
  "partner_reference": {
    "booking": {
      "id": "7d037cec-7d65-4ea9-8105-1247ee5f0a60",
      "number": "9967230:J00000000"
    }
  },
  "reasons": {
    "cancel": "Job has been cancelled"
  }
}

TRACKING​

{
  "status": "TRACKING",
  "job": {
    "id": "J000000000000000000",
    "number": 660531
  },
  "dates": {
    "event": "2026-07-09T01:05:00.000+01:00",
    "sent": "2026-07-09T01:05:00.100+01:00"
  },
  "allocation": {
    "type": "DRIVER",
    "driver": {
      "name": "SMITH, JOHN",
      "id": "33424",
      "callsign": "D56",
      "geo": {
        "lat": 51.472198,
        "long": -0.125747,
        "speed": 42.5,
        "bearing": 354,
        "time": "2026-07-09T01:05:00.000+01:00"
      }
    },
    "vehicle": {
      "class": "F",
      "reg": "AA00AAA",
      "model": "MULTIVAN LIFE PHEV S-A"
    }
  },
  "geo": {
    "lat": 51.472198,
    "long": -0.125747,
    "time": "2026-07-09T01:05:00.000+01:00"
  },
  "heading": {
    "address": {
      "formatted_address": "Euston Station, Melton Street, London, NW1 2EP"
    },
    "estimates": {
      "distance": 4200,
      "time": "PT6M"
    },
    "status": "ON_TRACK"
  }
}