Skip to content

Report journey 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 a driver and a 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 at short, regular intervals:

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 previous guides asked for a position about every 30 seconds; the onboarding prototype asked for at most 15 seconds between positions. Sending every 15 seconds meets both.

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 can move the journey on from the position. When positions show the driver within about 100 metres of the pickup while the journey is DRIVER_UNDERWAY, Transferz can set DRIVER_ARRIVED itself; near the drop-off it can set 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.
  • Assign the driver first. The Transfer Companies API accepts stage updates and positions for a journey without a driver, but the traveller and the partner then have no driver to look for.

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.

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?