v1

latestOpenAPI 3.0.0Cabify Api support2026-07-264588127.9 KB

Journeys

Create a 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.

post/api/v4/journey

Request body

label_slugstring 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.

messagestring 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_idstring nullable

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

product_idstring 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.

reasonstring 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_idstring 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.

start_atstring 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

Example request

{
  "label_slug": null,
  "message": "Test message for driver",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "reason": "Test reason for driver",
  "requester_id": "081a70a52cfc11ecbb03a25a490feee4",
  "rider": {
    "email": "riderEmail@example.com",
    "locale": "ES",
    "mobile": {
      "mobile_cc": "34",
      "mobile_num": "123456789"
    },
    "name": "Jhon Doe"
  },
  "start_at": "2022-07-01 10:00:00",
  "stops": [
    {
      "addr": "Madrid Barajas T1",
      "city": "Madrid",
      "contact": {
        "mobile_cc": "34",
        "mobile_num": "123456789",
        "name": "Jhon Doe",
        "stop_action": "pickup"
      },
      "country": "ES",
      "loc": [
        40.4722,
        -3.5608
      ],
      "location_id": "location-4",
      "meeting_point": {
        "id": "mp-loc4-1",
        "loc": [
          40.4722,
          -3.5608
        ],
        "name": "Terminal 1"
      },
      "name": "Work",
      "num": "1428"
    },
    {
      "addr": "Calle de la cruz",
      "city": "Madrid",
      "country": "ES",
      "loc": [
        40.4169335,
        -3.7061872
      ]
    }
  ]
}

Response

Success

idstring

journey_id of the current operation.

Example response

{
  "id": "0397896-19aa-11ed-b6fe-7aaea8067492"
}