GuidesAPI Reference
Guides
  1. Driver Events

Driver Events Model

Understand the Driver Events model, supported event types and recommended event sequence.

The Driver Events API uses a standard set of events to represent key moments during a transfer.

Each event records what happened and when it happened. Events can also include the driver's GPS location when available.

Event types

Below is the list of supported event types. Use the event names as shown when sending events through the API.

Event TypeDescription
DRIVER_DEPARTED_TO_PICKUPThe driver has departed towards the pickup location.
DRIVER_ARRIVED_AT_PICKUPThe driver has arrived at the pickup location and is waiting for the passengers.
DRIVER_SUBMITTED_CUSTOMER_NO_SHOWThe driver has reported that the customer did not show up at the pickup location.
DRIVER_DEPARTED_TO_DROPOFFThe passengers are onboard and the driver has departed towards the drop-off location.
DRIVER_ARRIVED_AT_DROPOFFThe driver has arrived at the drop-off location and the transfer is complete.
DRIVER_LIVE_LOCATIONProvides the driver's current GPS location during the transfer. This event can be sent periodically while the service is active.

Driver Location

When sending a Driver Event, we recommend including the driver's location using latitude and longitude, when available.

Location data is optional for most event types and required for DRIVER_LIVE_LOCATION.

Below is an example of a basic Driver Event payload. Each event represents a specific moment during the transfer.

{
  "eventType": "DRIVER_DEPARTED_TO_PICKUP",
  "occurredAt": "2025-11-18T15:00:00+01:00"
}
{
  "eventType": "DRIVER_DEPARTED_TO_PICKUP",
  "occurredAt": "2025-11-18T14:00:00Z"
}

occurredAt format

You can send the timestamp as:

  • Local time with a UTC offset (e.g., "2025-11-18T15:00:00+01:00")
  • Or as UTC time with Z (e.g., "2025-11-18T14:00:00Z")

We recommend using local time with the correct UTC offset, as this allows accurate normalization of the event time across different time zones.

You can optionally include the driver's location in the event payload using:

  • latitude: the driver's latitude at the time of the event.
  • longitude: the driver's longitude at the time of the event.

These fields are required for DRIVER_LIVE_LOCATION.

For example:

{
  "eventType": "DRIVER_DEPARTED_TO_PICKUP",
  "occurredAt": "2025-11-18T15:00:00+01:00",
  "latitude": 3.232312211,
  "longitude": -3.31231
}

You can now send the Driver Event using the Create Driver Event endpoint:

curl --location '{{tracking_host_api_url}}/api/v1/suppliers/{supplierCode}/bookings/{{bookingRef}}/events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic base64(username:password)}' \
--data '{
  "eventType": "DRIVER_DEPARTED_TO_PICKUP",
  "occurredAt": "2025-11-18T15:00:00+01:00",
  "latitude": 3.232312211,
  "longitude": -3.31231
}'
curl --location '{{tracking_host_api_url}}/api/v1/suppliers/{supplierCode}/bookings/{{bookingRef}}/events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic base64(username:password)}' \
--data '{
  "eventType": "DRIVER_ARRIVED_AT_PICKUP",
  "occurredAt": "2025-11-18T15:00:00+01:00",
  "latitude": 3.432312211,
  "longitude": -3.51231
}'

When the event is successfully recorded, the API returns a 201 Created status with no content in the response body.

📘

Live Location

You can send DRIVER_LIVE_LOCATION multiple times during the transfer to provide updated driver location data.
Each DRIVER_LIVE_LOCATION event must include the latitude and longitude .

Recommended Event Workflow

We recommend sending the following events to provide a complete view of the transfer journey:

  • DRIVER_DEPARTED_TO_PICKUP: The driver is on the way to the pickup location.
  • DRIVER_ARRIVED_AT_PICKUP: The driver has reached the pickup location and is waiting for the passenger.
  • DRIVER_DEPARTED_TO_DROPOFF: The passenger is onboard and the driver is on the way to the drop-off location.
  • DRIVER_ARRIVED_AT_DROPOFF: The driver has reached the drop-off location and the transfer is complete.

Sending these events in sequence gives Suntransfers a consistent view of the transfer as it progresses.

Why DRIVER_ARRIVED_AT_PICKUP Matters

DRIVER_ARRIVED_AT_PICKUP is particularly important because it tells Suntransfers that the driver has reached the pickup location and is waiting for the passenger.

This event enables us to provide customers with visibility that their driver has arrived, so it is important that it is sent when the driver reaches the pickup location and with an accurate occurredAt timestamp.

Additional Driver Events

  • DRIVER_LIVE_LOCATION: Provides updated GPS location data during the transfer. This event can be sent periodically and must include latitude and longitude.
  • DRIVER_SUBMITTED_CUSTOMER_NO_SHOW: Reports that the customer did not show up at the pickup location.

Updated 5 days ago

What’s Next