---
title: "Create a journey"
method: POST
path: "/api/v4/journey"
tags: ["Journeys"]
---

# Create a journey

`POST /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:
1. `hire` - Searching for available drivers
2. `hired` - Driver assigned and en route
3. `arrived` - Driver at pickup location
4. `pick up` - Passenger in vehicle
5. `drop off` - Journey completed
6. `terminated` - Receipt generated (after ~2 hours)
For a detailed explanation of journey states and their transitions, see [Journey States](https://developers.cabify.com/docs/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](https://developers.cabify.com/docs/sandbox-environment) for details.

## Request body

- JourneyRequest — 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, nullable — 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, nullable — 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, nullable — 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, nullable — 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 — 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` Rider, required — Input data defining the rider of a journey.
    - `email` string, email, nullable — Rider's email.
    - `id` string — Id of the Rider that will travel, if the Rider is a User of your company this will be the User's id (can be same as requester_id to request a journey for yourself). Leave empty when the Rider is external to your company.
    - `locale` string, nullable — Rider's Locale. Syntax consists of language two-letter tag which then will be suffixed with Client's country.
    - `mobile` Mobile — Input Mobile Number. Required when the rider is external. Journey's SMS state updates will arrive to this mobile.
      - `mobile_cc` string, required — Mobile Country Code. Required if mobileNum is provided.
      - `mobile_num` string, required — Rider's phone number.
    - `name` string — Rider's name. Required when the rider is external.
  - `start_at` string, nullable — 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` StopRequest[], required
    - `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` Contact — Contact details on each Stop. Include this object if you want the Driver to see additional Contact details on each Stop.
      - `mobile_cc` string — Mobile Country Code of the Contact of the Stop passed when creating the Journey.
      - `mobile_num` string — Mobile Number of the Contact of the Stop passed when creating the Journey.
      - `name` string — Name of the Contact of the Stop passed when creating the Journey.
      - `stop_action` 'pickup' | 'dropoff' — Action to be performed on the Stop. Possible values: 'pickup', 'dropoff'. Ignored when it is included in the `contact` field (`stop/contact`), i.e. only taken into account when specific for the contacts within `stop/contacts`.
    - `contacts` Contact[] — List of contacts for the stop. Only one of `contact` or `contacts` should be provided.
      - `mobile_cc` string — Mobile Country Code of the Contact of the Stop passed when creating the Journey.
      - `mobile_num` string — Mobile Number of the Contact of the Stop passed when creating the Journey.
      - `name` string — Name of the Contact of the Stop passed when creating the Journey.
      - `stop_action` 'pickup' | 'dropoff' — Action to be performed on the Stop. Possible values: 'pickup', 'dropoff'. Ignored when it is included in the `contact` field (`stop/contact`), i.e. only taken into account when specific for the contacts within `stop/contacts`.
    - `country` string — Country name where the address is located, e.g. Spain.
    - `instr` string — Set of instructions for the Driver.
    - `loc` number[], required — The actual coordinates of the address. Required floats per location latitude and longitude.
    - `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` MeetingPoint — 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.
      - `id` string, required — Unique identifier of the meeting point.
      - `loc` number[], required — Coordinates of the meeting point as [latitude, longitude].
      - `name` string, required — Display name of the meeting point.
    - `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.

## Response `200`

Success

- JourneyResponse
  - `id` string — journey_id of the current operation.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `500` — Internal server error

---

[API](https://skmtc.dev/cabify/apis/ride-hailing-api.md) · [All operations](https://skmtc.dev/cabify/apis/ride-hailing-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cabify/ride-hailing-api/revisions/8da1cb1270df/schema)