How a journey reaches you
How journeys reach a transfer company, by direct assignment or through the offer flow.
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.
Two ways in
A traveller books a ride through a partner, for example from Amsterdam Airport Schiphol to a hotel in the city. Transferz then gives the journey to a transfer company in one of two ways. Which one applies to you is part of your agreement with Transferz; many companies receive journeys both ways.
Direct assignment. Transferz assigns the journey to one of your fleets straight away. You do not have to do anything to get it. Transferz can also assign a journey to you by hand.
Offer flow. Transferz offers the journey to your company first. You accept or decline the offer
before its expiry. Only when you accept is the journey assigned to your fleet. An offer can also be
open to several companies at once; the first to accept gets the journey and the others see the offer
as MISSED.
Either way, the result is the same: the journey is assigned to your fleet and you receive
journeyFleetAssignedEvent. From then on there is no
difference between the two flows.
| Step | Direct assignment | Offer flow |
|---|---|---|
| 1 | — | You receive offerCreatedEvent. |
| 2 | — | You accept or decline the offer. |
| 3 | You receive journeyFleetAssignedEvent. | After you accept, you receive journeyFleetAssignedEvent. |
| 4 | You fetch the journey and plan it. | The same. |
An offer has an offer id and the journey has a journey id; they are different numbers. You use the
offer id only to accept or decline. After that, everything uses the journeyId.
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 on staging.
Then continue with Receive journeys by webhook.