Guides
Cabify BusinessAPI Support

Ride-Hailing API Changelog

All notable changes to the Ride-Hailing API will be documented in this file.

API Evolution Approach

  • Continuous Enhancement: The API follows a continuous enhancement model where new features are added to v4 without breaking existing functionality
  • No Breaking Changes: All new features are additive and backward compatible
  • API Version: All endpoints are available under /api/v4/
  • Legacy Support: v3 GraphQL endpoints remain available at /api/v3/graphql for existing integrations

[4.0] - Current REST API

Added

Flexible Rides

  • New Flexible Rides service (2026-08-12): Added support for a new service that manages the new Flexible Ride entity, to allow integrations with it. This adds 5 new endpoints:
  • API Endpoints:
    • POST /api/v4/flexible_rides/ - to create a Flexible Ride
    • GET /api/v4/flexible_rides/{flexible_ride_id] - to Fetch a Flexible Ride by its ID
    • PATCH /api/v4/flexible_rides/{flexible_ride_id} - to Update a Flexible Ride
    • DELETE /api/v4/flexible_rides/{flexible_ride_id} - to Cancel a Flexible Ride
    • GET /api/v4/flexible_rides/?status={status} - to List Flexible Rides owned by the user. Supports pagination and filter by status

Webhooks

  • Account identification header (2026-08-07): Outbound webhooks now include an X-CABIFY-CLIENT-ID header carrying the account's public client_id (the same value already present in the body as data.client_id)
    • Lets you identify which account an event belongs to without parsing the body — useful when a single integration handles multiple accounts
    • Non-breaking: the header is purely additive and the OAuth UUID (HMAC key) is never transmitted
    • See the Webhook Headers guide for details

Last-Stop Drop-off pick up Event (2026-07-22)

  • For journeys that use enriched stops (per-stop contacts), the final stop now emits its own pick up webhook, consistent with intermediate stops and with the documented "one pick up per stop" behavior.
    • Previously the last drop-off was folded into the finished event and produced no stop-level webhook, so its stop_id / stop_contacts / stop_action were never delivered.
    • The finished and terminated events are unchanged — they still carry null stop_id / stop_contacts.
    • This change is additive and scoped to enriched-stops journeys: those integrators now receive one extra pick up event (for the last stop) on drop-off completion. Journeys without enriched stops are unaffected.

Hub Experience

  • Hub Meeting Point Support (2026-05-06): Added hub discovery and meeting point selection for large venues (airports, train stations)
    • Integrators can now specify a precise pickup location within a hub (e.g. a terminal at an airport or a specific platform at a train station)
    • The meeting_point object contains id, loc (coordinates), and name fields
    • Hub meeting point data is surfaced via the hub field in the POST /api/v4/estimates response (origin stop only)
    • The hub field is identical across all estimation objects and is best-effort — it may be null if hub resolution does not complete before pricing
    • When a hub is present, the selected meeting point should be included in the journey creation request
    • API Endpoints:
      • POST /api/v4/estimates — response now includes hub inside each estimation object (origin stop only, non-breaking)
      • GET /api/v4/hub?latitude={lat}&longitude={lng} — standalone endpoint to look up hub data by coordinates; returns { data: null } when no hub exists at the location
      • POST /api/v4/journey — stop objects now accept an optional meeting_point: { id, loc, name }
    • Example flow:
      1. Call POST /api/v4/estimates — check if the response includes a hub object
      2. Alternatively, call GET /api/v4/hub?latitude=40.47&longitude=-3.56 to look up hub data directly
      3. Present meeting points to the user for selection
      4. Include the selected meeting point in the journey creation request:
      {
  "loc": [40.4888902, -3.5799743],
  "addr": "Madrid Barajas",
  "meeting_point": {
    "id": "2ae0e801-f118-4833-bd1b-c4dc2d2de662",
    "loc": [40.4888902, -3.5799743],
    "name": "Madrid Barajas T4"
  }
}

Webhooks

  • Hot-Hire Status Events (2026-07-20): New "hot-hired" state in journey-state webhooks
    • Notifies integrators when the assigned driver is currently completing another trip before heading to pickup
    • New webhook state value: "hot-hired" — distinct from "hired", safe to ignore for integrators that don't need hot-hire data
    • New fields (only present in hot-hired events):
      • is_driver_on_another_journey (boolean): true while driver is on another trip
      • driver_stop_before_pickup (object or null): driver's intermediate stop as {"loc": [lat, lng]}
    • Multiple hot-hired events per journey are expected as data is enriched (detected → coordinates added → ended)
    • Backward compatible: existing integrations are unaffected unless they explicitly handle the new state
    • Documentation: Journey State Updates — Hot-Hired Event

Journey State

  • Hot-Hire Fields in REST State (2026-07-20): Added hot-hire information to the journey state response
    • GET /api/v4/journey/{journey_id}/state now includes:
      • is_driver_on_another_journey (boolean): whether the assigned driver is on another trip
      • driver_stop_before_pickup (object or null): driver's intermediate stop as {"loc": [lat, lng]}
    • Fields are populated from the corporate-mobility service when a driver is assigned
    • Graceful degradation: defaults to false / null if the upstream service is unavailable
    • API Endpoint: GET /api/v4/journey/{journey_id}/state

Journey Management

  • Preferred Driver ID Validation (2026-07-07): POST /api/v4/journey now validates the format of preferred_driver_id

    • When provided by a client entitled to use it, preferred_driver_id must be a hyphen-less UUID (^[a-f0-9]{32}$); malformed values (e.g. trailing characters, whitespace, or non-UUID strings) are rejected with 400 Bad Request
    • Prevents malformed IDs from being accepted and silently failing driver preassignment later
    • No change for clients not entitled to the feature: the field continues to be ignored

  • Preassigned Driver (2026-06-30): Added a preassigned_driver object to the journey state

    • Exposed in both GET /api/v4/journey/{journey_id}/state (REST) and the GraphQL state object
    • Surfaces the driver preassigned to a journey (typically a reservation) before the journey is formally assigned
    • Contains id, name and avatar_url. name is the driver's first name only. Unlike driver, it does not include the phone number, since the preassigned driver is not yet confirmed and should not be contacted
    • Informative only: it may change or disappear before the journey starts, and the state stays hire while a driver is preassigned. driver always takes precedence once a driver is assigned
    • The journey-state webhook also carries a flat preassigned_driver_id, populated on hire events when a driver is preassigned (and null otherwise)
    • Example state response: 
      {
  "journey_id": "f0397896-19aa-11ed-b6fe-7aaea8067492",
  "name": "hire",
  "preassigned_driver": {
    "id": "e8417e8cd14c11ec869eb2e3f32e3b38",
    "name": "Diana",
    "avatar_url": "https://secure.gravatar.com/avatar/675ee8c314586d36a7b33c6c773565e9?r=pg&s=80&=blank"
  }
}

  • Stop Action Support (2025-10-13): Added stop_action field to Contact model

    • New field allows specifying whether a contact is for pickup or dropoff
    • Enables better driver instructions and passenger management
    • Supports both single contact (contact) and multiple contacts (contacts) per stop
    • Valid values: "pickup", "dropoff"
    • Example usage in journey creation: 
      {
  "stops": [
    {
      "loc": [40.4169335, -3.7061872],
      "contacts": [
        {
          "name": "John Doe",
          "mobile_cc": "+1",
          "mobile_num": "555-0123",
          "stop_action": "pickup"
        }
      ]
    }
  ]
}
    • API Endpoints:
      • POST /api/v4/journey - Enhanced with stop action support
      • GET /api/v4/journey/{journey_id} - Improved response with enhanced contact information
      • GET /api/v4/journey/{journey_id}/state - Enhanced state information

  • Custom Driver Messages for Multi-Passenger Journeys (2025-10-13): Enhanced journey creation with automatic driver message composition

    • Automatically generates detailed passenger information for drivers in multi-stop journeys
    • Includes passenger names, contact details, and pickup locations
    • Only applies when stop_action is provided for contacts
    • Example message: "Trayecto con 2 pasajeros | Pasajero John Doe - TEL +1 555-0123 - 123 Main St"
    • API Endpoint: POST /api/v4/journey - Enhanced with driver message features

  • Multiple Contacts Per Stop Support (2025-08-05): Added support for multiple contacts per stop in journey creation

    • New contacts array field allows specifying multiple passengers per stop
    • Supports both single contact (contact) and multiple contacts (contacts) per stop
    • Automatically generates driver instructions for multiple passengers
    • Enables complex multi-passenger journey scenarios
    • API Endpoint: POST /api/v4/journey - Enhanced with multiple contacts support

  • Keep Searching Feature (2025-02-11): Added ability to extend driver search for existing journeys

    • Allows continuing driver search for journeys that didn't find drivers initially
    • Extends search time by 5 minutes without requiring new estimation
    • Maintains original pricing from initial estimation
    • Can be called multiple times to extend search duration
    • API Endpoint: POST /api/v4/journey/{journey_id}/keep_searching

Enhanced

Journey States

  • Improved Journey State Management (2025-10-13): Enhanced journey state tracking and webhook events
    • Better support for multi-stop journey state transitions
    • Enhanced webhook events for driver assignments and passenger pickups
    • Improved error handling and state validation

Webhooks

  • Self-service webhook configuration (2026-09-09): Admin users now set, change and remove the webhook URL themselves, from the Integrations section of the Cabify web app
    • Each environment keeps its own webhook, so production and testing are configured separately
    • Clearing the field stops the updates
    • Configuring a webhook no longer requires contacting support
  • Enrich Webhook State Events (2026-03-12): Added Location information to some webhook state events
    • Events where the driver location can be known (hired, arrived, pick up, finished)
    • It reflects the driver's location at the moment the state transition occurred
    • Example: "loc": [40.4138, -3.7061]
  • Enhanced Webhook Events (2025-08-06): Improved webhook functionality for multi-passenger journeys
    • Contact Information in Webhooks: Webhooks now return contact information for multiple passengers
    • Journey State Events: Improved webhook payloads for multi-passenger journeys
    • Driver Assignment Events: Enhanced driver information in webhook events
    • Passenger Pickup Events: Better tracking of passenger pickup/dropoff actions

Previous Versions

[3.0] - Previous GraphQL API

  • GraphQL-based API with comprehensive journey management
  • User management and sales tracking
  • Label management for journey categorization

[2.0] - Legacy REST API (Deprecated)

  • Initial REST API implementation
  • Basic journey management functionality
  • Status: Fully deprecated, no longer supported

Support

For questions about these changes or API integration support, please contact:

Updated about 1 month ago

Did this page help you?