Report journey progress
Report driver underway, arrived and in progress, and send the driver's live position.
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
| Stage | Status | Call |
|---|---|---|
| The driver leaves for the pickup | DRIVER_UNDERWAY | Driver underway |
| The driver is at the pickup and waiting | DRIVER_ARRIVED | Driver arrived |
| The traveller is on board | JOURNEY_IN_PROGRESS | In progress |
| The traveller was dropped off | COMPLETED | Complete 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:
/journeys/488213/status/driver-underwayReferencecurl --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"}'HTTP/1.1 204 No Contentlatitude 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:
/journeys/488213/driver-positionReferencecurl --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"}'HTTP/1.1 204 No ContentThe 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:
/journeys/488213/status/driver-arrivedReferencecurl --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"}'HTTP/1.1 204 No ContentStep 4: Traveller on board
When the traveller is in the car and you leave for the drop-off:
/journeys/488213/status/in-progressReferencecurl --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"}'HTTP/1.1 204 No ContentKeep 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
204and 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 setDRIVER_ARRIVEDitself; near the drop-off it can setCOMPLETED. WatchjourneyStatusChangedEventand 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
| Status | Code | Cause | What to do |
|---|---|---|---|
400 | JOURNEY_STATUS_CHANGE_NOT_ALLOWED_IF_PICKUP_TIME_TOO_FAR_IN_FUTURE | The pickup is more than 48 hours away. | Send stage updates on the day of the journey. |
400 | STATUS_TRANSITION_NOT_ALLOWED | The 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. |
403 | INSUFFICIENT_PERMISSIONS | The 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.