# Look up and search journeys

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

Section: Transfer companies · Last updated: 2026-11-15

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:

**Request:** [`GET /journeys/488213`](https://developers.test.transferz.com/reference/transfer-companies/get-journey)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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](https://developers.test.transferz.com/reference/transfer-companies/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:

**Request:** [`GET /journeys`](https://developers.test.transferz.com/reference/transfer-companies/search-journeys)

```bash title="cURL"
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'
```

```javascript title="JavaScript"
const response = await fetch("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", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("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")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "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");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('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');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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](https://developers.test.transferz.com/guides/essentials/conventions#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:

**Request:** [`GET /journeys`](https://developers.test.transferz.com/reference/transfer-companies/search-journeys)

```bash title="cURL"
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'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=100&updatedAfter=2026-11-30T06:00:00&sort=id;asc", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("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")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=100&updatedAfter=2026-11-30T06:00:00&sort=id;asc");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=100&updatedAfter=2026-11-30T06:00:00&sort=id;asc');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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).

> **To be confirmed by Transferz:** The time zone of the `updatedAfter`, `createdAfter` and similar filters is still to be confirmed by
> Transferz. Pickup filters compare with the pickup time.

## 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](https://developers.test.transferz.com/guides/get-started/authentication). |

A search that matches nothing returns `200` with an empty `results` list.

## Related

### Endpoints

- [GET Get journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)
- [GET Search journeys](https://developers.test.transferz.com/reference/transfer-companies/search-journeys) (`GET /journeys`)
