Follow a journey
Follow a journey's status, driver and vehicle by webhook or polling, and get its voucher.
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:
| Event | When | Typical status after it |
|---|---|---|
journeyStatusChangedEvent | The journey's status changed | Any |
journeyDriverAssignedEvent | The transfer company assigned a driver | PLANNED |
journeyDriverVehicleAssignedEvent | A vehicle was assigned to the driver | PLANNED |
journeyDriverPositionUpdatedEvent | The driver reported a new position | DRIVER_UNDERWAY onwards |
A status change looks like this:
{ "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:
{ "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:
/journeys/488213Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "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:
/journeys/488213/voucherReferencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213/voucher' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'HTTP/1.1 303 See OtherLocation: https://files.example.com/vouchers/TZ7K4QM-1.pdfFollow 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 journeycode; - the driver's
nameandphoneNumber; - the vehicle:
vehicleMake,vehicleModelandvehicleLicensePlate; - the meeting point
name,descriptionand itsfiles, 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
| Problem | Cause | What to do |
|---|---|---|
403 with INSUFFICIENT_PERMISSIONS | The journey belongs to another partner. | Check the journey id and the API key. |
404 from Get journey | No journey with this id in this environment. | Check the id and the environment. |
204 from Get voucher | No voucher yet. | Try again after the journey is CONFIRMED. |
| No events arrive | Endpoint not registered, or the events are not enabled. | Ask Transferz to check your webhook registration. |
| Events stop for one journey | An earlier event for that journey keeps failing. | Fix your endpoint; see Order. |
Next steps
- Change a journey when the traveller's plans change.
- Cancel a journey or a booking.
Related
Walk-through