Create a journey

post

https://cabify-sandbox.com/api/v4/journey

Creates a new journey request for a ride.

❗️
Prerequisites
Before creating a journey, you must call the /estimates endpoint and use the returned
product.id as product_id in this request. This guarantees that the product is available
at the pickup location and provides accurate pricing shown to drivers.
The estimate should be created within 5 minutes of the journey request.

Journey States

After creation, the journey progresses through these states:

hire - Searching for available drivers
hired - Driver assigned and en route
arrived - Driver at pickup location
pick up - Passenger in vehicle
drop off - Journey completed
terminated - Receipt generated (after ~2 hours)
For a detailed explanation of journey states and their transitions, see Journey States.

📘
Booking a Journey (Reservation)
Creating a reservation is similar to creating an ASAP journey, except for the start_at field,
which should contain a future date-time value in the format "YYYY-MM-DD HH:MM:SS", expressed
in the local time of the pickup location.
Use the same start_at value you provided to the /estimates endpoint to ensure consistent
product availability and pricing between the estimate and the journey creation.
Important constraints:

Reservations must be created at least 30 minutes before the start time

Reservations can be scheduled up to 60 days in advance

⚠️
Sandbox Testing
In the sandbox environment, pickup locations must be within central Madrid (approximately 40.4361°, -3.7014°).
See Sandbox Environment for details.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Journey request

Input object needed to create a new journey.

⚠️
Always estimate before creating a journey
You must call /estimates before creating a journey. The estimation response provides:

product.id — the product to book

Pricing and availability information valid at the time of the estimate

Pass product.id as product_id in this request. For reserved journeys, also pass the same
start_at you used in the estimation request to guarantee consistent pricing and availability.
We recommend estimating no more than 5 minutes before creating the journey.

label_slug

string | null

If your company has the labels feature enabled (used to categorize expenses, receipts) than a valid label can be provided and it will be associated to a journey for later financial reporting purposes. Custom string which does not allow an empty string value '' Note that it can have a null value.

message

string | null

A message that be associated to a journey that driver can see after they accept the ride. It's usually used to give any extra information that might help the driver in the pickup or to give any information that might help improving the journey experience.

preferred_driver_id

string | null

Id of the preferred driver for this journey (UUID without hyphens). Only available for clients that have their own driver fleet.

product_id

string

required

The product/vehicle category to book. Must come from a recent /estimates response (product.id). Products are dynamic and vary by location and time — never hardcode IDs. Always estimate first to discover available products.

reason

string | null

Free text explaining the motive of the journey. It is available later in all expenditure reports together with the label (if used). Note that this has to be a valid string if the company decides to have this field as mandatory.

requester_id

string

required

^[a-f0-9]{32}$

It represents the person who creates the ride and is also the passenger of the ride. Nevertheless if the rider object is provided then the passenger (rider) is a different person (check rider attribute for more info). The value of requesterIdshould correspond to a user.id of an registered user in the account.

rider

object

required

Input data defining the rider of a journey. If your platform books journeys on behalf of your own end customers (e.g. the customers of a marketplace or app built on top of Cabify) and those customers never need to log into Cabify's own apps, we recommend leaving id empty and providing name/mobile instead, rather than creating a User per customer. This avoids having to manage account activation for people who never interact with Cabify directly, and still lets the rider follow their journey and contact the driver through the journey's public_url.

start_at

string | null

[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]

Defines when the journey should start. Format: YYYY-MM-DD HH:MM:SS (local time of the pickup location).

ASAP rides: Leave as null (or omit the field).
Reservations: Set to a future time. Use the same start_at value you provided in the /estimates request to ensure consistent product availability and pricing.
- Minimum: 30 minutes from now
- Maximum: 60 days in advance

stops

array of objects

required

length between 2 and 15

stops*

Stop of a journey. A journey needs to have at least 2 stops: the first one is considered the pickup point the last one the destination.

addr

string

If an address was provided when creating the journey this field will have its value.

city

string

City name where the address is located, e.g. Madrid.

contact

object

Contact details on each Stop. Include this object if you want the Driver to see additional Contact details on each Stop.

contacts

array of objects

List of contacts for the stop. Only one of contact or contacts should be provided.

contacts

country

string

Country name where the address is located, e.g. Spain.

instr

string

Set of instructions for the Driver.

loc

array of floats

required

length between 2 and 2

Defaults to []

The actual coordinates of the address. Required floats per location latitude and longitude.

loc*

location_id

string

Internal location identifier for hub stops. Required when a meeting_point is provided. Obtained from the hub data returned by GET /hub or POST /estimates.

meeting_point

object

A specific meeting point within a hub location (e.g. a terminal at an airport). Obtained from the hub data returned in the estimates response.

name

string

A short name for previously stored addresses. These can be viewed in places.

num

string

Street number.

postal_code

string

Postal code of the address.

Stop of a journey. A journey needs to have at least 2 stops: the first one is considered the pickup point the last one the destination.

addr

string

If an address was provided when creating the journey this field will have its value.

city

string

City name where the address is located, e.g. Madrid.

contact

object

Contact details on each Stop. Include this object if you want the Driver to see additional Contact details on each Stop.

contacts

array of objects

List of contacts for the stop. Only one of contact or contacts should be provided.

contacts

country

string

Country name where the address is located, e.g. Spain.

instr

string

Set of instructions for the Driver.

loc

array of floats

required

length between 2 and 2

Defaults to []

The actual coordinates of the address. Required floats per location latitude and longitude.

loc*

location_id

string

Internal location identifier for hub stops. Required when a meeting_point is provided. Obtained from the hub data returned by GET /hub or POST /estimates.

meeting_point

object

A specific meeting point within a hub location (e.g. a terminal at an airport). Obtained from the hub data returned in the estimates response.

name

string

A short name for previously stored addresses. These can be viewed in places.

num

string

Street number.

postal_code

string

Postal code of the address.

Always estimate before creating a journey

200Success

400Bad request

401Unauthorized

404Not found

500Internal server error