Polling

Overview

With polling, your platform asks Suntransfers for the Driver Events of a booking whenever it needs them, instead of waiting for Suntransfers to send them.

Each event has the fields and values described in Event Types & Data Model, the same as the events Suntransfers sends to your endpoint. You can use polling on its own, or together with receiving events on your endpoint, for example to recover events your endpoint did not receive.

For each leg of the booking, the response contains the latest event of each event type. For DRIVER_LIVE_LOCATION, this is the driver's last known position.

Prerequisites

Before getting started, you will need:

• Your Partners API credentials. Polling uses the same credentials, hosts and token as the rest of the Partners API.
• Driver Events enabled for your account. Ask your Suntransfers contact if you are not sure.

Authentication

Get a token with a POST /authentication request, as described in Authentication. The token is valid for an hour.

Send the token in the Authorization header of every request:

Authorization: Bearer {TOKEN}

When the token expires, the API answers 401. Request a new token and send the request again.

Get the Driver Events of a booking

GET /v1/bookings/{ref}/driver-events

curl --location --request GET 'https://api.staging.suntransfers.biz/v1/bookings/SUNTR_AB1234/driver-events' \
--header 'Authorization: Bearer {TOKEN}'

Response

The body is a JSON object with an events array. Each item is an event object, as described in Event Types & Data Model.

{
  "events": [
    {
      "bookingReference": "SUNTR_AB1234",
      "externalReference": "AGENCY_REF_1",
      "transferPosition": 2,
      "eventType": "DRIVER_ARRIVED_AT_PICKUP",
      "occurredAt": "2026-07-08T18:10:00+02:00",
      "latitude": 41.38,
      "longitude": 2.17
    },
    {
      "bookingReference": "SUNTR_AB1234",
      "externalReference": "AGENCY_REF_1",
      "transferPosition": 2,
      "eventType": "DRIVER_DEPARTED_TO_PICKUP",
      "occurredAt": "2026-07-08T17:40:00+02:00",
      "latitude": null,
      "longitude": null
    },
    {
      "bookingReference": "SUNTR_AB1234",
      "externalReference": "AGENCY_REF_1",
      "transferPosition": 2,
      "eventType": "DRIVER_LIVE_LOCATION",
      "occurredAt": "2026-07-08T18:09:30.5+02:00",
      "latitude": 41.3874,
      "longitude": 2.1686
    }
  ]
}

• Each leg (transferPosition) has at most one event of each event type: the latest one.
• Only legs with Driver Events enabled are included.
• events is an empty array when the driver has not sent any event yet, when no leg of the booking has Driver Events enabled, or when the booking is cancelled.

Errors

The 404, 503 and 500 errors have a JSON body with a status and an info message:

{
  "status": "error",
  "info": "Booking not found"
}

Polling best practices

• Poll only while the transfer is in progress. Start shortly before the pickup time and stop when every leg has a DRIVER_ARRIVED_AT_DROPOFF or DRIVER_SUBMITTED_CUSTOMER_NO_SHOW event. To avoid unnecessary requests, we also recommend setting a maximum polling window based on the scheduled pickup time, in case the expected final event is never received.
• Detect new events by occurredAt. Since each leg and event type returns only the latest event, compare occurredAt with the value you already have to know whether an event is new or updated.
• Back off on errors. After a 429, 503 or 500, wait before the next request and increase the wait if the error repeats.

How to get started

1. Understand Driver Events. Review the available event types and their data structure in Event Types & Data Model.
2. Test in Staging. Request the Driver Events of a Staging booking and check that your integration processes the response.
3. Go live. Once testing is complete, send the same requests to the Production host.