CAcabify
Flexible Rides

Create a Flexible Ride

Changed on

Creates a new Flexible Ride.

❗️ Prerequisites

Before creating a flexible ride, you should call the /estimates endpoint and use the returned product.id as product_id in this request. This should also give you an estimate on how much the journey could cost at claim time, but is not guaranteed for this use case, as the cost is set at claim time.

Flexible Ride states

After created, a Flexible Ride can end up in these states:

  1. pending - Initial state.
  2. claimed - It was claimed by a user and a journey was created for it.
  3. failed - A non recoverable error ocurred during the claiming process (e.g overbudget).
  4. cancelled - It was cancelled by the owner.
  5. expired - After the expiration time was reached.

Of note is that all states besides pending are final. A Flexible Ride can be modified and claimed while it's pending, but it becomes read only after it is changed to any other state.

📘 Expiration

Take into account that if you set a claimable_since time, the calculation of the expiration time for the Flexible Ride will take it into consideration (expires_at will be set N seconds after claimable_since)

⚠️ 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/flexible_rides

Request

  • Base URL
    https://cabify-sandbox.com
  • URL
    https://cabify-sandbox.com/api/v4/flexible_rides
  • Auth
    HTTP bearer

Request body

claimable_sincestring nullable

UTC ISO 8601 timestamp since when the flexible ride can be claimed.

expires_in_secondsinteger nullable

Seconds until the Flexible Ride expires, counted from claimable_since, or from creation if it is not set. Between 3600 (1 hour) and 259200 (3 days). Defaults to 86400 (24 hours).

label_slugstring nullable

Cost-center / project code.

messagestring nullable

Driver-visible message to be set on create journey.

product_idstring

ID of the vehicle category/product used for this flexible ride, as returned by the estimates endpoint.

reasonstring nullable

Journey reason to be set once created.

requester_idstring

ID of the user who requested the flexible ride.

rider_metadataobject nullable

Client metadata

sender_namestring nullable

Alias that is going to be displayed as the sender of the flexible ride on the claim page.

Example request

{
  "claimable_since": "2022-08-04T19:28:18.375Z",
  "expires_in_seconds": 3600,
  "label_slug": "apiV4",
  "max_price": {
    "amount": 100,
    "currency": "EUR"
  },
  "message": "driver message",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "reason": "reservation",
  "requester_id": "0dfc7c0bbbd300e6f9212827106e8911",
  "rider": {
    "email": "riderEmail@example.com",
    "locale": "ES",
    "mobile": {
      "mobile_cc": "34",
      "mobile_num": "123456789"
    },
    "name": "Jhon Doe"
  },
  "rider_metadata": {},
  "sender_name": "sender",
  "stops": [
    {
      "addr": "Calle de la cruz",
      "city": "Madrid",
      "contact": {
        "mobile_cc": "34",
        "mobile_num": "123456789",
        "name": "Jhon Doe",
        "stop_action": "pickup"
      },
      "country": "ES",
      "id": "123",
      "loc": [
        40.4169335,
        -3.7061872
      ],
      "name": "Work",
      "num": "1428"
    }
  ]
}

Response

Success

claimable_sincestring nullable

UTC ISO 8601 timestamp since when the flexible ride can be claimed.

expires_atstring nullable

ISO 8601 datetime when the flexible ride will expire.

idstring

ID of the flexible ride.

inserted_atstring

UTC ISO 8601 creation timestamp.

journey_idstring nullable

ID of the journey associated to the flexible ride, once claimed.

label_slugstring nullable

Cost-center / project code.

messagestring nullable

Driver-visible message to be set on create journey.

product_idstring

ID of the vehicle category/product used for this flexible ride, as returned by the estimates endpoint.

public_urlstring

URL Path that links to the page to claim the flexible ride.

reasonstring nullable

Journey reason to be set once created.

requester_idstring

ID of the user who requested the flexible ride.

rider_metadataobject nullable

Client metadata.

sender_namestring nullable

Alias that is going to be displayed as the sender of the flexible ride on the claim page.

statusstring

Status of the flexible ride (can be one of: pending, claimed, failed, expired, cancelled).

updated_atstring

UTC ISO 8601 last-update timestamp.

Example response

{
  "claimable_since": "2022-08-04T19:28:18.375Z",
  "expires_at": "2022-08-04T19:28:18.375Z",
  "id": "0dfc7c0bbbd300e6f9212827106e8911",
  "inserted_at": "2022-02-17T09:30:34.831Z",
  "journey_id": "96fc6f24-142b-11ed-bba7-56a6f40ef0bf",
  "label_slug": "apiV4",
  "max_price": {
    "amount": 100,
    "currency": "EUR"
  },
  "message": "driver message",
  "product_id": "75dd566797369d1f0927102e5356ce59",
  "public_url": "/fr/5ceg7v77qm8x28c9",
  "reason": "reservation",
  "requester_id": "0dfc7c0bbbd300e6f9212827106e8911",
  "rider": {
    "email": "riderEmail@example.com",
    "locale": "ES",
    "mobile": {
      "mobile_cc": "34",
      "mobile_num": "123456789"
    },
    "name": "Jhon Doe"
  },
  "rider_metadata": {},
  "sender_name": "sender",
  "status": "pending",
  "stops": [
    {
      "addr": "Calle de la cruz",
      "city": "Madrid",
      "contact": {
        "mobile_cc": "34",
        "mobile_num": "123456789",
        "name": "Jhon Doe",
        "stop_action": "pickup"
      },
      "country": "ES",
      "id": "123",
      "loc": [
        40.4169335,
        -3.7061872
      ],
      "name": "Work",
      "num": "1428"
    }
  ],
  "updated_at": "2022-08-04T19:28:18.375Z"
}

Changes