The journey lifecycle
A journey from assignment to completion, what your integration does at each stage, and the statuses it moves through.
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. You then fetch the journey and plan
it.
What you do with a journey
Once a journey is yours, your integration:
- Receives the journey by webhook and fetches its details with Get a journey.
- Assigns a driver and a vehicle. The
journey moves from
CONFIRMEDtoPLANNED. - Reports 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.
- Completes the journey after the drop-off.
Along the way you may also need to:
- handle changes and cancellations that Transferz sends you;
- report a no-show with evidence;
- update pickup information for shared journeys;
- report that the host met the traveller for meet and greet journeys;
- look up and search 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.
Before you start
You need:
- a staging account and an API key; see Getting started;
- an HTTPS webhook endpoint registered in the workspace; see Webhooks;
- a test journey; the workspace books one for you, see Test data.
Then continue with Receive journeys.
Related
Endpoints