# Follow a journey

> Follow a journey's status, driver and vehicle by webhook or polling, and get its voucher.

Section: Partners · Last updated: 2026-11-15

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](https://developers.test.transferz.com/guides/partners/create-a-booking) and, for real-time updates, a
[webhook endpoint](https://developers.test.transferz.com/guides/essentials/webhooks).

## Step 1: Receive events

Transferz sends partners these events by webhook. Each carries the `journeyId`:

| Event                                                                                                                   | When                                   | Typical status after it   |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------- |
| [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed)          | The journey's status changed           | Any                       |
| [`journeyDriverAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/driver-assigned)                | The transfer company assigned a driver | `PLANNED`                 |
| [`journeyDriverVehicleAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/vehicle-assigned)        | A vehicle was assigned to the driver   | `PLANNED`                 |
| [`journeyDriverPositionUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/driver-position-updated) | The driver reported a new position     | `DRIVER_UNDERWAY` onwards |

A status change looks like this:

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

```json
{
  "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](https://developers.test.transferz.com/guides/essentials/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](https://developers.test.transferz.com/workspace). Transferz switches on the
event types you need.

> **To be confirmed by Transferz:** Partner self-service of the webhook URL is built on the staging endpoints but not yet confirmed against live
> staging, and partners cannot yet choose their event types themselves.

## 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](https://developers.test.transferz.com/reference/partners/get-journey):

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

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/partners/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/partners/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/partners/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/partners/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/partners/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": "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.

> **To be confirmed by Transferz:** Rate limits are still to be confirmed by Transferz.

## Step 3: Get the voucher

Once a transfer company has the journey (`CONFIRMED`), Transferz issues a PDF voucher for the
traveller. [Get voucher](https://developers.test.transferz.com/reference/partners/get-journey-voucher) answers `303 See Other` with the address of the PDF
in the `Location` header:

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

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

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/journeys/488213/voucher", {
  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/partners/journeys/488213/voucher"))
        .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/partners/journeys/488213/voucher");
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/partners/journeys/488213/voucher');
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 (303):**

```http
HTTP/1.1 303 See Other
Location: https://files.example.com/vouchers/TZ7K4QM-1.pdf
```

Follow 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 journey `code`;
- the driver's `name` and `phoneNumber`;
- the vehicle: `vehicleMake`, `vehicleModel` and `vehicleLicensePlate`;
- the meeting point `name`, `description` and its `files`, 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](https://developers.test.transferz.com/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](https://developers.test.transferz.com/guides/essentials/test-data#partners-run-a-journey).

## 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](https://developers.test.transferz.com/guides/essentials/webhooks#order). |

## Next steps

- [Change a journey](https://developers.test.transferz.com/guides/partners/change-a-journey) when the traveller's plans change.
- [Cancel a journey or a booking](https://developers.test.transferz.com/guides/partners/cancel-a-journey-or-booking).

## Related

### Endpoints

- [GET Get journey by id](https://developers.test.transferz.com/reference/partners/get-journey) (`GET /journeys/{journeyId}`)
- [GET Get journey voucher](https://developers.test.transferz.com/reference/partners/get-journey-voucher) (`GET /journeys/{journeyId}/voucher`)

### Walk-through steps

- [Follow the ride](https://developers.test.transferz.com/walkthrough/partner/follow-the-ride)
