Skip to content

Understanding our booking endpoints

What does it do?

The booking endpoints provide details about all bookings allocated to you, allowing you to retrieve and manage them.

Note

Bookings automatically transition to COMPLETE status 6 hours after the pickup time. Completed bookings are not returned by the list endpoint but can still be retrieved via the single booking endpoint.

High-level Flow

1. Authenticate    →  Exchange clientId:clientSecret for a JWT token
2. Get bookings    →  GET /v1/bookings (with filters & pagination)
3. Accept/Reject   →  POST /v1/bookings/:customerReference/:bookingReference/responses
4. Assign driver   →  POST /v2/bookings/:bookingReference/assignDriver
5. Send events     →  POST /v1/bookings/:customerReference/:bookingReference/driver/events
  1. Authenticate — obtain an access token using your Client ID and Client Secret.
  2. Fetch bookings — call GET /v1/bookings to retrieve all bookings assigned to you. Use status filters and pagination to manage large result sets.
  3. Retrieve a single booking — call GET /v1/bookings/:customerReference/:bookingReference to get full details. The response includes a state_hash needed for the next step.
  4. Accept or reject — call POST /v1/bookings/:customerReference/:bookingReference/responses with the latest state_hash to transition the booking status.
  5. Assign a driver — once accepted, assign driver and vehicle details via POST /v2/bookings/:bookingReference/assignDriver. See Driver Management.

Warning

Rejecting a booking counts as a "Decline" and impacts your quality metrics. We strongly advise against automating rejections.

Note

Bookings are also sent via email. Once your API integration is functioning, you can disregard the email notifications.

Key Concepts

Booking Statuses & Transitions

Bookings move through several states that may require action from you. See booking statuses & transitions for the full state machine.

Pagination

Responses are paginated with a default page size of 400 (maximum 500). The response includes a links array with a next href for retrieving subsequent pages using cursor-based pagination. See pagination details.

Responses include a links array providing paths for relevant actions (pagination, accept, reject). Use these links to navigate the API rather than constructing URLs manually.

Booking Ordering

Bookings are returned in booked_date descending order (newest first).

Further reading