Skip to content

How a journey reaches you

How journeys reach a transfer company, by direct assignment or through the offer flow.

Updated · 3 min read

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.

StepDirect assignmentOffer flow
1—You receive offerCreatedEvent.
2—You accept or decline the offer.
3You receive journeyFleetAssignedEvent.After you accept, you receive journeyFleetAssignedEvent.
4You 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:

  1. Receives the journey by webhook and fetches its details with Get a journey.
  2. Assigns a driver and a vehicle. The journey moves from CONFIRMED to PLANNED.
  3. 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.
  4. Completes the journey after the drop-off.

Along the way you may also need to:

The statuses you see

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

StatusWhat it means for youWho sets it
CONFIRMEDThe journey is yours. It still needs a driver.Transferz
PLANNEDA driver is assigned.Transferz, when you assign a driver
DRIVER_UNDERWAYThe driver is on the way to the pickup.You or the Driver App
DRIVER_ARRIVEDThe driver is at the pickup.You, the Driver App, or Transferz from the driver's position
JOURNEY_IN_PROGRESSThe traveller is on board.You or the Driver App
COMPLETEDThe traveller was dropped off.You, the Driver App, or Transferz from the driver's position
CANCELLED_FREECancelled; you are not paid for it.Transferz
CANCELLED_WITH_COSTSCancelled; 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:

Then continue with Receive journeys by webhook.

Was this helpful?