References¶

Send a driver event¶

Push driver events to a booking to keep customers informed during the journey.

POST /v1/bookings/:customerReference/:bookingReference/driver/events

Note

Each event type can only be sent once per booking, except DRIVER_LIVE_LOCATION. Duplicate events are silently ignored after the first submission.

Warning

Events must be sent in chronological order. Sending events out of sequence will return a 400 error. The first event must always be DRIVER_DEPARTED_TO_PICKUP.

Live driver tracking¶

Send DRIVER_LIVE_LOCATION events every 5 seconds with GPS coordinates to provide real-time tracking to customers.

Requirement	Detail
Frequency	Every 5 seconds (gold standard). Maximum gap: 20 seconds — data beyond this is considered unusable.
Required fields	`latitude` and `longitude` must be provided
Start	After sending `DRIVER_DEPARTED_TO_PICKUP`
Stop	After sending `DRIVER_ARRIVED_AT_DROPOFF`

Tracking will appear to the customer once the first DRIVER_LIVE_LOCATION event is received and will terminate when DRIVER_ARRIVED_AT_DROPOFF is sent.

Request¶

Field	Type	Description	Required
event_type	String	One of the following: `DRIVER_DEPARTED_TO_PICKUP` `DRIVER_ARRIVED_AT_PICKUP` `DRIVER_SUBMITTED_CUSTOMER_NO_SHOW` `DRIVER_DEPARTED_TO_DROPOFF` `DRIVER_ARRIVED_AT_DROPOFF` `DRIVER_LIVE_LOCATION`	Yes
latitude	Number	The latitude where the event occurred. Up to 8 decimal places.	Required for `DRIVER_LIVE_LOCATION`. Strongly recommended for all other events.
longitude	Number	The longitude where the event occurred. Up to 8 decimal places.	Required for `DRIVER_LIVE_LOCATION`. Strongly recommended for all other events.
occurred_at	String	The datetime the event occurred in UTC (ISO 8601). Must not be in the future.	Yes

Sample Request — Driver event¶

{
    "event_type": "DRIVER_DEPARTED_TO_PICKUP",
    "latitude": 53.4883114,
    "longitude": -2.2522131,
    "occurred_at": "2020-08-28T12:05:01Z"
}

Sample Request — Live location¶

{
    "event_type": "DRIVER_LIVE_LOCATION",
    "latitude": 53.48114132,
    "longitude": -2.24033433,
    "occurred_at": "2020-11-17T12:05:01Z"
}

Response¶

HTTP 200 - OK¶

{
  "message": "event sent successfully"
}

HTTP 400 - Event time in the future¶

{
  "message": "Invalid Input Parameter",
  "description": "Event time is after current time"
}

HTTP 400 - Event time before driver assignment¶

{
  "message": "Invalid Input Parameter",
  "description": "Event time is before driver assignation time"
}

HTTP 400 - Invalid event sequence¶

{
  "message": "Invalid Input Parameter",
  "description": "Event <EventName> not allowed after last event submitted <LastEventName>"
}

HTTP 400 - Event time before last event¶

{
  "message": "Invalid Input Parameter",
  "description": "Event time is before last event time"
}

HTTP 400 - Invalid first event¶

{
  "message": "Invalid Input Parameter",
  "description": "Event <EventName> not allowed as first event"
}

HTTP 401 - Unauthorized¶

{
  "message": "Invalid Authorization Token",
  "description": "Invalid authorization token in header"
}

HTTP 404 - Not Found¶

{
  "message": "Not Found",
  "description": "Booking Not Found"
}