Skip to content

Look up and search journeys

Get one journey by id or search your journeys with filters and pagination.

Updated · 4 min read

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:

GET/journeys/488213Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "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:

GET/journeysReference
Sign in to fill in your staging key. Sign in
curl --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'
Response 200
{  "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:

GET/journeysReference
Sign in to fill in your staging key. Sign in
curl --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'
Response 200
{  "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.

FilterReturns journeys …
journeyId, journeyCodewith this id or code (TZ7K4Q-1)
bookingId, bookingCodeof this booking
driverCodewith this driver code
pickupDateAfter, pickupDateBeforewith a pickup in this range
updatedAfter, updatedBeforechanged in this range
createdAfter, createdBeforecreated in this range
completedOnAfter, completedOnBeforecompleted in this range
cancelledAfter, cancelledBeforecancelled in this range
includedStatuses, excludedStatusesin, or not in, these statuses
assignedTransferCompanyId, assignedFleetIdof these companies or fleets, when your account manages several
travellerEmailAddress, travellerNameof this traveller
heldForComplaintheld (true) or not held (false) because of a complaint
hubCountrywhose 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

FieldMeaning
idThe journey id (journeyId in events). Use it in every call about this journey.
codeThe journey reference shown to the traveller and the driver.
pickup, dropoffbookerEnteredAddress is what the booker typed; resolvedAddress and fullResolvedAddress are what Transferz resolved. hub is true for an airport, port or station.
pickupTimeLocal time at the pickup location, with its timeZone. Not UTC.
typeHUB (to or from a hub) or POINT_TO_POINT.
addonsPerQuantityAdd-ons and how many of each. addOns is deprecated.
distance, durationRoute distance in distanceUnit and expected driving time in seconds.
fareSummaryWhat you are paid for the journey.
meetingPointWhere the driver meets the traveller.
driverCodeThe code a driver uses to open this journey in the Driver App.
assignmentStatusASSIGNED when the journey is yours; REASSIGNED when it has moved to another company.
travellerInfoTraveller, passengers, luggage, travel details and driverComments (requests from the traveller).
driver, vehicleWhat you assigned; null until then.
lastKnownDriverPositionThe last position you or the Driver App sent.
hostTravellerMetTime, hostTravellerMetPositionWhen and where the host met the traveller, for meet and greet.
hashA 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

StatusCodeCauseWhat to do
400MAX_PAGE_SIZE_LIMIT_EXCEEDEDsize 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.
403INSUFFICIENT_PERMISSIONSGet 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.

Was this helpful?