Guides
Cabify BusinessAPI Support

Journey Creation Use Cases

This document provides detailed use cases for creating journeys and receiving real-time updates through webhooks. It covers the four main scenarios for journey creation and the complete flow from request to completion.

Overview

The Cabify Business API supports four primary journey creation scenarios:

  1. Rider is the requester - The person creating the journey is also the passenger
  2. Rider requests for another user - A registered user creates a journey for another registered user
  3. Rider requests for a guest - A registered user creates a journey for an external guest
  4. Rider requests for guests with multiple stops - A registered user creates a multi-stop journey for multiple guests

Journey Lifecycle and States

All journeys progress through the following states:

  • hire - Cabify is searching for an available driver
  • hired - Driver has been assigned and is en route to pickup location
  • arrived - Driver has arrived at the pickup location
  • pick up - Passenger is in the vehicle and journey is in progress
  • drop off - Journey completed successfully
  • terminated - Receipt generated (automatic after ~2 hours)

End States (Journey Completion)

Journeys can end in several ways:

  • drop off - Successful completion
  • rider cancel - Cancelled by the rider
  • driver cancel - Cancelled by the driver
  • no show - Rider didn't show up at pickup
  • not found - No driver was found

Use Case 1: Rider is the Requester

Scenario

A registered user creates a journey for themselves.

API Request Example

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

{
  "requester_id": "591bbf5d7db7d84023ca3760ba1f1000",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "stops": [
    {
      "addr": "Calle de la cruz, 1428",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4169335, -3.7061872],
      "name": "Pickup Location",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "34",
        "mobile_num": "123456789"
      }
    },
    {
      "addr": "Plaza Mayor, 1",
      "city": "Madrid", 
      "country": "ES",
      "loc": [40.4153635, -3.7073987],
      "name": "Destination"
    }
  ]
}

Key Points

  • requester_id and rider_id are the same
  • No rider object needed in the request
  • User must be registered in the system

Use Case 2: Rider Requests for Another User

Scenario

A registered user (e.g., executive assistant) creates a journey for another registered user (e.g., their manager).

API Request Example

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

{
  "requester_id": "591bbf5d7db7d84023ca3760ba1f1000",
  "rider_id": "591bbf5d7db7d84023ca3760ba1f1001",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "stops": [
    {
      "addr": "Calle de la cruz, 1428",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4169335, -3.7061872],
      "name": "Manager's Office",
      "contact": {
        "name": "Manager Name",
        "mobile_cc": "34",
        "mobile_num": "987654321"
      }
    },
    {
      "addr": "Plaza Mayor, 1",
      "city": "Madrid",
      "country": "ES", 
      "loc": [40.4153635, -3.7073987],
      "name": "Meeting Location"
    }
  ]
}

Key Points

  • requester_id and rider_id are different
  • Both users must be registered in the system
  • No rider object needed (uses existing user data)

Use Case 3: Rider Requests for a Guest

Scenario

A registered user creates a journey for an external guest (not registered in the system).

API Request Example

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

{
  "requester_id": "591bbf5d7db7d84023ca3760ba1f1000",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "rider": {
    "name": "Guest Name",
    "email": "[email protected]",
    "mobile": {
      "mobile_cc": "34",
      "mobile_num": "555666777"
    },
    "locale": "ES"
  },
  "stops": [
    {
      "addr": "Calle de la cruz, 1428",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4169335, -3.7061872],
      "name": "Guest Pickup",
      "contact": {
        "name": "Guest Name",
        "mobile_cc": "34",
        "mobile_num": "555666777"
      }
    },
    {
      "addr": "Plaza Mayor, 1",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4153635, -3.7073987],
      "name": "Guest Destination"
    }
  ]
}

Key Points

  • requester_id is the registered user
  • rider object contains guest information
  • Guest contact information is required
  • No rider_id needed (guest is not registered)
👍

Recommended for consumer-facing (B2C) platforms

If you're building a platform where your requester_id books journeys on behalf of your own end customers, this is the recommended pattern instead of creating a User per customer — see Users Management for why.

Use Case 4: Rider Requests for Guests with Multiple Stops

Scenario

A registered user creates a multi-stop journey for multiple guests, such as a corporate event with multiple pickup and drop-off locations.

API Request Example

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

{
  "requester_id": "591bbf5d7db7d84023ca3760ba1f1000",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "stops": [
    {
      "addr": "Calle de la cruz, 1428",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4169335, -3.7061872],
      "name": "First Guest Pickup",
      "contacts": [
        {
          "name": "Guest One",
          "mobile_cc": "34",
          "mobile_num": "111222333"
        }
      ]
    },
    {
      "addr": "Plaza Mayor, 1",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4153635, -3.7073987],
      "name": "Second Guest Pickup",
      "contacts": [
        {
          "name": "Guest Two",
          "mobile_cc": "34",
          "mobile_num": "444555666"
        }
      ]
    },
    {
      "addr": "Puerta del Sol, 1",
      "city": "Madrid",
      "country": "ES",
      "loc": [40.4167754, -3.7037902],
      "name": "Event Venue",
      "contacts": [
        {
          "name": "Event Coordinator",
          "mobile_cc": "34",
          "mobile_num": "777888999"
        }
      ]
    }
  ]
}

Key Points

  • Multiple stops (minimum 2, maximum 15)
  • Each stop can have multiple contacts using contacts array
  • Journey progresses through each stop sequentially
  • Webhook events include stop_id and stop_contacts for multi-stop journeys

Webhook Events and Real-time Updates

Webhook Configuration

All journey updates are sent via POST requests to your configured webhook endpoint. The webhook payload structure includes:

{
  "type": "journey-state",
  "data": {
    "client_id": "512cc654f0e342efcdd3fdfde9fd8000",
    "journey_id": "3fad6e43719a48f3904b5f2d54865b1a",
    "user_id": "591bbf5d7db7d84023ca3760ba1f1000",
    "rider_id": "591bbf5d7db7d84023ca3760ba1f1000",
    "state": "hired",
    "event_date": "2020-04-28T15:26:46.736462Z",
    "created_at": "2020-04-28T15:26:36Z",
    "start_type": "asap",
    "start_at": "2020-04-28T15:26:36Z",
    "driver_id": "1d254ba6aff9ddd82ff5543ae85a88eb",
    "finished_at": null,
    "terminated_at": null,
    "finish_reason": null,
    "stop_id": "d3b05d77-646a-46e5-bfd0-cf69a370afb8",
    "stop_contacts": [
      {
        "name": "Carlos Jesús",
        "mobile_cc": "34",
        "mobile_num": "677777777"
      }
    ]
  },
  "errors": []
}

Event Types

  1. Journey State Events - State changes (hire, hired, arrived, pick up, drop off, terminated)
  2. Location Updates - Real-time vehicle position (every 3 seconds during hired/pick up states)
  3. Public Info Updates - Driver and vehicle information updates

Location Update Example

{
  "type": "journey-location",
  "data": {
    "loc": [40.12660903930664, -3.1684000492095947],
    "journey_id": "3fad6e43719a48f3904b5f2d54865b1a",
    "event_date": "2020-04-28T15:26:49.571507Z",
    "client_id": "512cc654f0e342efcdd3fdfde9fd8000",
    "bearing": 0.0
  },
  "errors": []
}

Error Handling and Edge Cases

Common Failure Scenarios

  1. No Driver Found (not found state)

    • Use the keep_searching endpoint to continue searching
    • Journey will eventually timeout if no driver is found

  2. Rider Cancellation (rider cancel state)

    • Can cancel during hire, hired, or arrived states — but only before the first pick up
    • A cancel attempt after the first pick up returns 409 with {"message": "can't cancel journey at current state"}
    • May incur charges if driver is already assigned

  3. Driver Cancellation (driver cancel state)

    • Driver cancels the journey
    • No charges incurred

  4. No Show (no show state)

    • Rider doesn't appear at pickup location
    • May incur charges for waiting time

Webhook Reliability

  • Always use event_date to determine the most recent event
  • Implement idempotency to handle duplicate events
  • Events may arrive out of order - sort by event_date
  • Implement retry logic for failed webhook deliveries

Best Practices

Journey Creation

  • Always create an estimate before creating a journey
  • Ensure estimate is created within 5 minutes of journey request
  • Validate pickup locations are within service area
  • Use appropriate contact information for each stop

Webhook Handling

  • Implement proper authentication for webhook endpoints
  • Store and process events asynchronously
  • Handle duplicate events gracefully
  • Monitor webhook delivery success rates

Multi-stop Journeys

  • Plan efficient routes to minimize travel time
  • Provide clear instructions for each stop
  • Ensure contact information is accurate for each stop
  • Consider traffic patterns when scheduling

Testing in Sandbox

When testing these use cases in the sandbox environment:

  • Pickup locations must be within central Madrid (40.4361°, -3.7014°)
  • Simulated drivers may not always be available
  • Journey states transition automatically
  • Test both successful and failure scenarios

For more detailed information about specific API endpoints and webhook configurations, refer to the API Reference and Webhook Documentation.

Updated 2 months ago

Did this page help you?