Skip to content

Follow a journey

Follow a journey's status, driver and vehicle by webhook or polling, and get its voucher.

Updated · 3 min read

You will keep your system and the traveller up to date as a paid journey gets a transfer company, a driver and a vehicle, and as the ride happens. You need the journey id from Create a booking and, for real-time updates, a webhook endpoint.

Step 1: Receive events

Transferz sends partners these events by webhook. Each carries the journeyId:

EventWhenTypical status after it
journeyStatusChangedEventThe journey's status changedAny
journeyDriverAssignedEventThe transfer company assigned a driverPLANNED
journeyDriverVehicleAssignedEventA vehicle was assigned to the driverPLANNED
journeyDriverPositionUpdatedEventThe driver reported a new positionDRIVER_UNDERWAY onwards

A status change looks like this:

JSON
{  "journeyStatusChangedEvent": {    "created": "2026-11-20T10:47:12.381",    "journeyId": 488213,    "previousStatus": "PENDING",    "newStatus": "CONFIRMED"  }}

A driver assignment carries the driver's name and phone number:

JSON
{  "journeyDriverAssignedEvent": {    "created": "2026-11-30T18:05:44.120",    "journeyId": 488213,    "driver": {      "driverId": 77015,      "name": "Jordan Driver",      "phoneNumber": "+447700900199",      "driverPhoto": null    }  }}

Verify the signature of every event, answer 2xx quickly and process it afterwards, as described in Webhooks. Events for one journey arrive in order, but you can receive one twice.

Set your webhook URL and read the signing key in the workspace. Transferz switches on the event types you need.

Step 2: Fetch the journey

Events are short. To get the full picture, such as the transfer company, the meeting point and the vehicle, call Get journey:

GET/journeys/488213Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "id": 488213,  "code": "TZ7K4QM-1",  "vehicleCategory": "SEDAN",  "pickupTimeAdjustmentMethod": "FLIGHT_TRACKING",  "pickup": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" },  "transferCompany": { "id": 2290, "name": "Canal City Transfers", "phoneNumber": "+442079460150" },  "driver": {    "id": 77015,    "name": "Jordan Driver",    "phoneNumber": "+447700900199",    "vehicleId": 88120,    "vehicleMake": "Toyota",    "vehicleModel": "Corolla Touring",    "vehicleLicensePlate": "TZ-123-X",    "lastKnownPosition": { "latitude": 52.3462, "longitude": 4.9171 }  },  "meetingPoint": {    "id": 2561,    "type": "HUB",    "name": "Schiphol Plaza meeting point",    "description": "Walk to the Meeting Point sign in Schiphol Plaza, opposite arrivals 3. Your driver waits there with a name sign.",    "lat": 52.3094,    "lng": 4.7622,    "files": [{ "id": 99102, "fileType": "MAP", "url": "https://cdn.example.com/meeting-points/2561/map.png" }]  },  "status": "PLANNED",  "cancellationDetails": {    "cancellable": true,    "freeCancellationUntil": "2026-11-30T14:30:00",    "freeCancellationWindowHours": 24  },  "customerServiceInfo": { "supportPhoneNumber": "+442079460100" },  "travellerAppUrl": "https://traveller.example.com/j/TZ7K4QM-1"}

transferCompany, driver and meetingPoint are null until they are known. The pickup time can move when Transferz adjusts it to the flight; pickupTimeAdjustmentMethod says how it is adjusted.

If you do not use webhooks, poll Get journey for each upcoming journey and compare the status with the one you stored. Poll more often as the pickup approaches. Webhooks are the better choice: they arrive shortly after each change and cost you no requests.

Step 3: Get the voucher

Once a transfer company has the journey (CONFIRMED), Transferz issues a PDF voucher for the traveller. Get voucher answers 303 See Other with the address of the PDF in the Location header:

GET/journeys/488213/voucherReference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213/voucher' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 303
HTTP/1.1 303 See OtherLocation: https://files.example.com/vouchers/TZ7K4QM-1.pdf

Follow the Location header to download the PDF; most HTTP clients do this by default. While there is no voucher yet, for example when the journey is still PENDING, the answer is 204 No Content. A change to the journey issues a new voucher, so fetch it again after a change.

Step 4: Show the traveller what they need

Pass on what the traveller needs at pickup, and update it when it changes:

  • the pickup time (pickup.localTime) and place, and the journey code;
  • the driver's name and phoneNumber;
  • the vehicle: vehicleMake, vehicleModel and vehicleLicensePlate;
  • the meeting point name, description and its files, such as a map;
  • the customer service number in customerServiceInfo.supportPhoneNumber;
  • the voucher, or the travellerAppUrl.

Test it on staging

Bookings on staging are not driven by a real transfer company. Pay a booking, then use Send a test driver in the workspace: a simulated transfer company assigns a driver and a vehicle and moves the journey through its statuses, so your endpoint receives every event. See Test data on staging.

Errors

ProblemCauseWhat to do
403 with INSUFFICIENT_PERMISSIONSThe journey belongs to another partner.Check the journey id and the API key.
404 from Get journeyNo journey with this id in this environment.Check the id and the environment.
204 from Get voucherNo voucher yet.Try again after the journey is CONFIRMED.
No events arriveEndpoint not registered, or the events are not enabled.Ask Transferz to check your webhook registration.
Events stop for one journeyAn earlier event for that journey keeps failing.Fix your endpoint; see Order.

Next steps

Was this helpful?