# The journey lifecycle

> A journey from assignment to completion, what your integration does at each stage, and the statuses it moves through.

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

This page explains how a journey booked by a partner ends up with your company, and what your
integration does from that moment until the journey is completed. Read it before the task guides in
this section.

## How a journey becomes yours

A traveller books a ride through a partner, for example from Amsterdam Airport Schiphol to a hotel in
the city. Transferz then assigns the journey to one of your fleets. You do not have to do anything to
get it. Transferz can also assign a journey to you by hand.

When a journey is assigned to your fleet, you receive
[`journeyFleetAssignedEvent`](https://developers.transferz.com/reference/webhooks/journey-assigned). You then fetch the journey and plan
it.

## What you do with a journey

Once a journey is yours, your integration:

1. [Receives the journey by webhook](https://developers.transferz.com/guides/transfer-companies/receive-journeys) and
   fetches its details with [Get a journey](https://developers.transferz.com/reference/transfer-companies/get-journey).
2. [Assigns a driver and a vehicle](https://developers.transferz.com/guides/transfer-companies/assign-driver-and-vehicle). The
   journey moves from `CONFIRMED` to `PLANNED`.
3. [Reports progress](https://developers.transferz.com/guides/transfer-companies/report-progress): driver underway, driver
   arrived, traveller on board, and the driver's position on the way. Or your drivers use the
   Transferz Driver App, which does this for you.
4. [Completes the journey](https://developers.transferz.com/guides/transfer-companies/complete-a-journey) after the drop-off.

Along the way you may also need to:

- [handle changes and cancellations](https://developers.transferz.com/guides/transfer-companies/changes-and-cancellations)
  that Transferz sends you;
- [report a no-show](https://developers.transferz.com/guides/transfer-companies/report-a-no-show) with evidence;
- [update pickup information](https://developers.transferz.com/guides/transfer-companies/shared-journeys) for shared
  journeys;
- [report that the host met the traveller](https://developers.transferz.com/guides/transfer-companies/meet-and-greet) for meet and
  greet journeys;
- [look up and search journeys](https://developers.transferz.com/guides/transfer-companies/find-journeys) to keep your
  planning in sync.

## The statuses you see

A journey's `status` tells you where it is. As a transfer company you see these:

| Status                 | What it means for you                          | Who sets it                                                  |
| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| `CONFIRMED`            | The journey is yours. It still needs a driver. | Transferz                                                    |
| `PLANNED`              | A driver is assigned.                          | Transferz, when you assign a driver                          |
| `DRIVER_UNDERWAY`      | The driver is on the way to the pickup.        | You or the Driver App                                        |
| `DRIVER_ARRIVED`       | The driver is at the pickup.                   | You, the Driver App, or Transferz from the driver's position |
| `JOURNEY_IN_PROGRESS`  | The traveller is on board.                     | You or the Driver App                                        |
| `COMPLETED`            | The traveller was dropped off.                 | You, the Driver App, or Transferz from the driver's position |
| `CANCELLED_FREE`       | Cancelled; you are not paid for it.            | Transferz                                                    |
| `CANCELLED_WITH_COSTS` | Cancelled; you are paid for it.                | Transferz                                                    |

Journeys in the early statuses (`NOT_PAID`, `AWAITING_APPROVAL`, `PENDING`) are not yet yours, and you
receive no status events for them. `COMPLETED` and the two cancelled statuses are final. All values
are explained in [Constants](https://developers.transferz.com/guides/essentials/constants#journey-status).

## Before you start

You need:

- a staging account and an API key; see [Getting started](https://developers.transferz.com/guides/transfer-companies/getting-started);
- an HTTPS webhook endpoint registered in the [workspace](https://developers.transferz.com/workspace); see
  [Webhooks](https://developers.transferz.com/guides/essentials/webhooks);
- a test journey; the [workspace](https://developers.transferz.com/workspace) books one for you, see
  [Test data](https://developers.transferz.com/guides/essentials/test-data#transfer-companies-get-a-test-journey).

Then continue with [Receive journeys](https://developers.transferz.com/guides/transfer-companies/receive-journeys).

## Related

### Endpoints

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

### Certification cases

- [Direct assignment](https://developers.transferz.com/certification/transfer-companies/direct-assignment)
