# Find journeys

> Catch up on journeys after missed webhook events, get one journey by id, or search your journeys with filters.

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

Webhooks bring you every new journey and every change as it happens. But events can still go
missing: your endpoint may be down for a while, or Transferz gives up on an event after its last
retry (see [Webhooks](https://developers.staging.transferz.com/guides/essentials/webhooks#retries)). A regular sync with the endpoints on
this page is your safety net. It asks for every journey that changed since your last run, so your
system catches up and never works from an out-of-date journey. We recommend it for every
integration, even though it is optional.

You will fetch one journey by its id, list your journeys with filters, and set up that catch-up
sync. You need an API key.

## Step 1: Get one journey

Use the `journeyId` from a webhook event:

**Request:** [`GET /journeys/488213`](https://developers.staging.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.staging.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.staging.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.staging.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.staging.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).

`updatedAfter`, `createdAfter` and the other timestamp filters are in UTC. Pickup filters compare
with the pickup time, which is local.

## 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.staging.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.staging.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)
- [GET Search journeys](https://developers.staging.transferz.com/reference/transfer-companies/search-journeys) (`GET /journeys`)
