Skip to content

Report progress

Report driver underway, arrived and in progress, and send the driver's live position.

Updated · 4 min read

You will tell Transferz where the driver is, at each stage of the journey and continuously on the road, so the traveller and the partner can follow the car. You need an API key and a journey with a driver assigned (see Assign driver and vehicle).

There are two ways to do this: your own system calls the API, as described below, or your drivers use the Transferz Driver App and you integrate nothing.

The stages

StageStatusCall
The driver leaves for the pickupDRIVER_UNDERWAYDriver underway
The driver is at the pickup and waitingDRIVER_ARRIVEDDriver arrived
The traveller is on boardJOURNEY_IN_PROGRESSIn progress
The traveller was dropped offCOMPLETEDComplete a journey

Between the stages, send the driver's position regularly. Each stage call carries a position too.

Step 1: Driver underway

When the driver sets off for Schiphol, send the status with the driver's current position:

PUT/journeys/488213/status/driver-underwayReference
Sign in to fill in your staging key. Sign in
curl --request PUT \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-underway' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "latitude": 52.3462,  "longitude": 4.9171,  "recordedAt": "2026-12-01T12:40:00"}'
Response 204
HTTP/1.1 204 No Content

latitude and longitude are required in the body. recordedAt is the moment it happened, in UTC; leave it out to use the time of the request. Transferz then sends the traveller the driver's details, and you and the partner receive journeyStatusChangedEvent.

Status updates are accepted from 48 hours before the pickup time; earlier ones are refused.

Step 2: Send the position while driving

From driver underway until the drop-off, send the driver's position every 15 seconds:

PUT/journeys/488213/driver-positionReference
Sign in to fill in your staging key. Sign in
curl --request PUT \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/driver-position' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "latitude": 52.3091,  "longitude": 4.7624,  "recordedAt": "2026-12-01T13:12:05"}'
Response 204
HTTP/1.1 204 No Content

The partner receives each position as journeyDriverPositionUpdatedEvent, and the traveller sees the car move. The last position is returned as lastKnownDriverPosition by Get a journey.

The API does not enforce an interval. The certification section "Driver, vehicle and tracking" asks for at least 3 positions, each one different.

Step 3: Driver arrived

When the driver is at the pickup point and waiting for the traveller:

PUT/journeys/488213/status/driver-arrivedReference
Sign in to fill in your staging key. Sign in
curl --request PUT \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-arrived' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "latitude": 52.3091,  "longitude": 4.7624,  "recordedAt": "2026-12-01T13:12:05"}'
Response 204
HTTP/1.1 204 No Content

Step 4: Traveller on board

When the traveller is in the car and you leave for the drop-off:

PUT/journeys/488213/status/in-progressReference
Sign in to fill in your staging key. Sign in
curl --request PUT \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/in-progress' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "latitude": 52.3101,  "longitude": 4.7655,  "recordedAt": "2026-12-01T13:55:00"}'
Response 204
HTTP/1.1 204 No Content

Keep sending positions until the drop-off, then complete the journey.

Rules worth knowing

  • Send the stages in order. The API does not check the order: any status that is not final can be set from any other. If you send driver arrived after in progress, the journey goes back to DRIVER_ARRIVED.
  • Repeating a status is harmless. Sending the status the journey already has returns 204 and changes nothing, so retries are safe.
  • Transferz moves the journey on from the position. For every transfer company, when the driver's position reaches the pickup point while the journey is DRIVER_UNDERWAY, Transferz sets DRIVER_ARRIVED itself; when it reaches the drop-off point, Transferz sets COMPLETED. Watch journeyStatusChangedEvent and do not send an earlier stage after a later one has been set.
  • Always include the position. The body is optional on the stage calls, but Transferz measures whether driver underway, driver arrived and in progress came with a position, and certification requires a real one (not 0,0).
  • Assign the driver first. A driver is expected to be assigned before you send stage updates and positions. The Transfer Companies API still accepts them for a journey without a driver, but certification does not. Without a driver, the traveller and the partner have no driver to look for. Your company can have journeys with and without an assigned driver at the same time.

Or let your drivers use the Driver App

The Transferz Driver App runs in the phone's browser; nothing has to be installed. The driver opens the journey with its driverCode (three digits, three letters, three digits, such as 482KQM731), or from the link in the SMS sent when you assign the driver with notifyBySms set to true. The app sends the stages and the positions for you, so you do not call the endpoints on this page.

If your drivers use the app, say so in the certification section "Driver, vehicle and tracking": the steps for your own progress and position updates are then skipped.

The Driver App is at https://transferz.taxi in production and at https://staging.transferz.taxi/ on staging.

Errors

StatusCodeCauseWhat to do
400JOURNEY_STATUS_CHANGE_NOT_ALLOWED_IF_PICKUP_TIME_TOO_FAR_IN_FUTUREThe pickup is more than 48 hours away.Send stage updates on the day of the journey.
400STATUS_TRANSITION_NOT_ALLOWEDThe journey is completed or cancelled.Stop sending updates. If Transferz completed it from the position, there is nothing left to do.
400—latitude or longitude is missing from a body you sent.Send both.
403INSUFFICIENT_PERMISSIONSThe journey is not assigned to your company, or the id does not exist.Check the id; the journey may have been unassigned from you.
401—The API key is missing, wrong or expired.See Authentication.

The error format is described in Errors.

Was this helpful?