Journeys Booking

This section covers the mobility solution for all companies looking to transport their employees in a simple, safe and comfortable way. We offer different types of vehicles with private drivers and provide everything you need to enjoy your journey, such as a good driver and a top-of-the-range car.

What is a Journey?

Each time a user requests a ride on Cabify, a Journey object is created.
This object holds the information about the vehicle, driver, passenger (rider), traveled route, etc.
Through our API you'll be able to:

Create a new Journey (ASAP or Reservation)
Cancel an ongoing Journey
Obtain details of an ongoing or finished Journey
Webhooks: Receive live updates regarding changing data related to the Journey for example vehicle, driver, vehicle's position

The journey progresses through various states from creation to completion. For a detailed explanation of the journey lifecycle and state transitions, see Journey Updates via Webhooks.

Hub Meeting Points

When picking up from a large venue (airport, train station), you can specify a meeting point — a precise pickup location within the hub. This helps the driver navigate directly to the correct gate or platform.

To include a meeting point in a journey, add the meeting_point field to the origin stop:

{
  "stops": [
    {
      "loc": [40.402344, -3.688157],
      "addr": "Madrid Atocha - Bóvedas",
      "meeting_point": {
        "id": "e1cbfac4-7149-482d-95fa-0b69a7f464f8",
        "loc": [40.402344, -3.688157],
        "name": "Bobedas"
      }
    },
    {
      "loc": [40.4169335, -3.7061872],
      "addr": "Destination"
    }
  ]
}

Meeting point data can be obtained from:

The hub field in the POST /api/v4/estimates response
The standalone GET /api/v4/hub?latitude={lat}&longitude={lng} endpoint

📘
Meeting point is optional
If no meeting point is provided, the journey will be created normally using the stop coordinates.

📘
Try it in sandbox
The Atocha hub (uid 562f925c-b900-4c93-bdd9-15a3d621f02f) with the Bóvedas meeting point is available in the sandbox environment. See Sandbox Environment for the full example.

Understanding Users and Riders

In the Journey context, it's important to understand two key roles:

Requester: The person who creates the journey request (identified as requester_id)
Rider: The actual passenger who will take the trip (identified by rider_id)

These can be the same person or different people. For example, an executive assistant might create journeys for their manager.

⚠️
Sandbox Environment
In the testing environment, the simulated drivers are configured to operate only in Madrid. To test journeys, the pickup location must be within the central Madrid area: https://www.google.com/maps/@40.4361263,-3.7013768,16z
For more details about the sandbox environment limitations and behavior, see Sandbox Environment.