Look up and search journeys
Get one journey by id or search your journeys with filters and pagination.
You will fetch one journey by its id, list your journeys with filters, and catch up on everything that changed since your last sync. You need an API key.
Step 1: Get one journey
Use the journeyId from a webhook event:
/journeys/488213Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "id": 488213, "code": "TZ7K4Q-1", "pickup": { "bookerEnteredAddress": "AMS", "resolvedAddress": "Amsterdam Airport Schiphol (AMS), Evert van de Beekstraat 202, 1118 CP Schiphol, Netherlands", "fullResolvedAddress": { "streetName": "Evert van de Beekstraat", "streetNumber": "202", "city": "Schiphol", "postalCode": "1118 CP", "region": "Noord-Holland", "countryCode": "NL", "establishment": "Amsterdam Airport Schiphol" }, "latitude": 52.3105, "longitude": 4.7683, "hub": true, "iataCode": "AMS" }, "dropoff": { "bookerEnteredAddress": "Herengracht 182, Amsterdam", "resolvedAddress": "Herengracht 182, 1016 BR Amsterdam, Netherlands", "fullResolvedAddress": { "streetName": "Herengracht", "streetNumber": "182", "city": "Amsterdam", "postalCode": "1016 BR", "region": "Noord-Holland", "countryCode": "NL", "establishment": "Hotel Example Canal House" }, "latitude": 52.3738, "longitude": 4.8862, "hub": false, "iataCode": null }, "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "addonsPerQuantity": [{ "type": "MEET_GREET", "amount": 1 }], "vehicleCategory": "SEDAN", "type": "HUB", "distance": 19.8, "distanceUnit": "KILOMETER", "duration": 1560, "fareSummary": { "includingVat": 57, "excludingVat": 52.29, "vat": 4.71, "currency": "EUR", "geoZoneId": 801, "operationZoneId": 912 }, "status": "PLANNED", "meetingPoint": { "id": 2561, "title": "Schiphol Plaza meeting point", "description": "Walk to the Meeting Point sign in Schiphol Plaza, opposite arrivals 3.", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" }, "driverCode": "482KQM731", "assignmentStatus": "ASSIGNED", "travellerInfo": { "firstName": "Alex", "lastName": "Traveller", "email": "alex.traveller@example.com", "phone": "+447700900123", "meetAndGreetSignText": "Alex Traveller", "passengerCount": 2, "adultPassengerCount": 2, "childPassengerCount": 0, "infantPassengerCount": 0, "luggageCount": 3, "checkedLuggageCount": 2, "carryOnLuggageCount": 1, "driverComments": "Two suitcases and a stroller.", "flightNumber": "TZ1234", "trainNumber": null, "shipName": null, "language": "en" }, "partnerReference": "ORDER-10023", "driver": { "id": 77015, "name": "Jordan Driver", "phoneNumber": "+447700900456" }, "lastKnownDriverPosition": null, "vehicle": { "id": 88120, "licensePlate": "TZ-123-X", "makeName": "Toyota", "modelName": "Corolla Touring", "seriesName": "Hybrid" }, "hostTravellerMetTime": null, "hostTravellerMetPosition": null, "hash": "3b7f0c2a9d4e61f58a0b2c7d9e1f3a4b5c6d7e8f90a1b2c3d4e5f60718293a4b"}Step 2: Search your journeys
Search journeys returns the journeys assigned to your company, one page at a time. This request lists the confirmed and planned journeys with a pickup on 1 December, earliest first:
/journeysReferencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=20&pickupDateAfter=2026-12-01T00:00:00&pickupDateBefore=2026-12-02T00:00:00&includedStatuses=CONFIRMED&includedStatuses=PLANNED&sort=pickup;asc' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "pagination": { "currentPage": 0, "pageSize": 20, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 488213, "code": "TZ7K4Q-1", "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "vehicleCategory": "SEDAN", "status": "PLANNED", "assignmentStatus": "ASSIGNED", "partnerReference": "ORDER-10023" } ]}Each result has the same fields as Get a journey (shortened above). page starts at 0; size is
at most 100. Request pages until currentPage is totalPages - 1; see
Pagination.
Step 3: Catch up after missed events
Webhook events can be given up after their last attempt, and your endpoint can be down. Run a regular sync that asks for every journey changed since the last run:
/journeysReferencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=100&updatedAfter=2026-11-30T06:00:00&sort=id;asc' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "pagination": { "currentPage": 0, "pageSize": 100, "totalPages": 1, "totalResults": 1 }, "results": [ { "id": 488213, "code": "TZ7K4Q-1", "status": "PLANNED", "hash": "3b7f0c2a9d4e61f58a0b2c7d9e1f3a4b5c6d7e8f90a1b2c3d4e5f60718293a4b" } ]}Store the time you started the sync and use it as updatedAfter next time, with some overlap. Compare
each result with what you have; the hash helps (see below).
Filters
All filters are optional and can be combined. Dates are written as 2026-12-01T00:00:00, without a
time-zone offset. Lists, such as includedStatuses, are repeated:
includedStatuses=CONFIRMED&includedStatuses=PLANNED.
| Filter | Returns journeys … |
|---|---|
journeyId, journeyCode | with this id or code (TZ7K4Q-1) |
bookingId, bookingCode | of this booking |
driverCode | with this driver code |
pickupDateAfter, pickupDateBefore | with a pickup in this range |
updatedAfter, updatedBefore | changed in this range |
createdAfter, createdBefore | created in this range |
completedOnAfter, completedOnBefore | completed in this range |
cancelledAfter, cancelledBefore | cancelled in this range |
includedStatuses, excludedStatuses | in, or not in, these statuses |
assignedTransferCompanyId, assignedFleetId | of these companies or fleets, when your account manages several |
travellerEmailAddress, travellerName | of this traveller |
heldForComplaint | held (true) or not held (false) because of a complaint |
hubCountry | whose hub is in this country, as an ISO 3166-1 alpha-2 code such as NL |
Sort with sort, a field and a direction joined by a semicolon. The fields are id, created,
pickup and status, for example sort=pickup;asc.
Journeys awaiting approval by Transferz are never returned.
What the journey fields mean
| Field | Meaning |
|---|---|
id | The journey id (journeyId in events). Use it in every call about this journey. |
code | The journey reference shown to the traveller and the driver. |
pickup, dropoff | bookerEnteredAddress is what the booker typed; resolvedAddress and fullResolvedAddress are what Transferz resolved. hub is true for an airport, port or station. |
pickupTime | Local time at the pickup location, with its timeZone. Not UTC. |
type | HUB (to or from a hub) or POINT_TO_POINT. |
addonsPerQuantity | Add-ons and how many of each. addOns is deprecated. |
distance, duration | Route distance in distanceUnit and expected driving time in seconds. |
fareSummary | What you are paid for the journey. |
meetingPoint | Where the driver meets the traveller. |
driverCode | The code a driver uses to open this journey in the Driver App. |
assignmentStatus | ASSIGNED when the journey is yours; REASSIGNED when it has moved to another company. |
travellerInfo | Traveller, passengers, luggage, travel details and driverComments (requests from the traveller). |
driver, vehicle | What you assigned; null until then. |
lastKnownDriverPosition | The last position you or the Driver App sent. |
hostTravellerMetTime, hostTravellerMetPosition | When and where the host met the traveller, for meet and greet. |
hash | A fingerprint of the details that matter for planning (see below). |
The hash. hash changes when the pickup, the drop-off, the pickup time, the add-ons, the vehicle
category, the fare, the meeting point, the driver code, the assignment status, the traveller details
or the cancelled state changes. Store it, and when a sync returns a different value, update the
journey in your planning. It does not change when only the status moves from PLANNED to
DRIVER_UNDERWAY, or when you assign a driver or a vehicle.
Errors
| Status | Code | Cause | What to do |
|---|---|---|---|
400 | MAX_PAGE_SIZE_LIMIT_EXCEEDED | size is above 100. | Use 100 or less and page through the results. |
400 | — | A filter value is not valid, such as a date with an offset or an unknown status. | Check the format of the filter. |
403 | INSUFFICIENT_PERMISSIONS | Get a journey: the journey is not assigned to your company, or the id does not exist. | Check the id. |
401 | — | The API key is missing, wrong or expired. | See Authentication. |
A search that matches nothing returns 200 with an empty results list.
Related
Endpoints