Back to top

Cabify Public API

This is the public API offered by Cabify to 3rd parties for integration with our services. If you want to integrate the Cabify API in your service you need:

Choosing the language

The Accept-Language header

Response values that are available in multiple languages are provided in the language of the Cabify user owning the API key.

It is possible to specify another language by using the standard HTTP header Accept-Language. For instance:

Accept-Language: en

Currently accepted language codes are:

  • en: English (international)

  • es: Spanish (international)

    • es-ES: Spanish / Spain
  • ca: Catalan

  • pr: Portuguese (international)

    • pt-BR: Portuguese / Brasil

Note that this header will be processed by all API endpoints although it will not be shown.

Browser App Authentication

Authentication to the Cabify API uses OAuth. Before using the API, a client application must be created by Cabify.

OAuth Implicit flow

This authentication method is suitable for Javascript-only applications. Technical details are provided by the oauth rfc.

Request a token [GET oauth/authorizations/new?{client_id}{&redirect_uri}{&response_type}{&scope}{&state}]

⚠️ This is not an API call, the url must be displayed by the browser.

To get a token, the client application must redirect the user to this url, where it will be requested to authenticate (if needed) and to grant access to the requesting application.

See also the Oauth Implicit Grant Authorization Request

On successful authentication, the redirect_uri will be called with the token details in the URL fragment. See also the Oauth Implicit Grant Authorization Response

  • Request (text/html)

    • Parameters
      • client_id: 0987654321abcdef0987654321abcdef (string, required) - the unique id issued by Cabify for the client application.
      • response_type: token (string, required) - MUST have the value token
      • redirect_uri: https://example.com/foo - The URI to redirect after authorization. Must be under the URI provided for the client application.
      • scope: public_api (string, optional) - The authentication scope. It will default to the value configured for the client application.
      • state: Anything (string, optional) - Any value can be provided and it will be included in the redirection.
  • Response 200 (text/html) If the user needs to perform any action to grant access to the application (including authorizing on Cabify), an html page will be displayed.

Server App Authentication

Authentication to the Cabify API uses OAuth. Before using the API, a client application must be created by Cabify.

OAuth Authorization Code flow

This authentication method is suitable for applications with a backend component. To use it you need to implement the steps below:

  1. Your app should open a browser with the Request an authorization url.
  2. The user should fill the login form and if the email and password are correct, they will be redirected to the callback url which need to be configured by the API Support Team (please, contact with us if this is your case). This callback url will include a code parameter.
  3. With the code received in the callback url, you need to request an access token using the Get an authorization token endpoint using your client_id and client_secret, and setting the grant_type attribute to authorization_code. Please review the docs to see how to do the request. In the response you will receive a access_token. You need to store it and use it in the following request to the API. The access_token have a expire time defined by the expires_in attribute included in the response, this value is defined in seconds. When token expires, you should refresh it using the refresh token flow.
  4. To refresh a token you should request a new access_token using the Get an authorization token endpoint. In this case, you should set the attribute grant_type to refresh_token and code to the value of your refresh_token. In the response of the request you will get a new access_token you should use to do request to the API, and a new refresh_token you’ll need to use in the future to refresh again the access_token.

Request an authorization code [GET auth/authorizations/new?{client_id}{&response_type}]

⚠️ This is not an API call, the url must be displayed by the browser.

To get a token, the client application must redirect the user to this url, where it will be requested to authenticate.

On successful authentication, the callback url configured in the Oauth Application will be called with the authentication code in the URL fragment. (For example, https://your-web-app.com/oauth/cabify/callback?code=1234)

  • Request (text/html)

    • Parameters
      • client_id: 0987654321abcdef0987654321abcdef (string, required) - the unique id issued by Cabify for the client application.
      • response_type: code (string, required) - MUST have the value code
  • Response 200 (text/html) If the user needs to perform any action to grant access to the application (including authorizing on Cabify), an html page will be displayed.

Get an authorization token

Get an authorization token
POST/auth/api/authorization

With the authorization code that we got in the previous step, we can now perform a request to get the final authorization token that we need in order to authenticate an user.

Example URI

POST /auth/api/authorization
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "grant_type: `authorization_code`, `refresh_token` (string, required) - *MUST* have the value `authorization_code` or `refresh_token`.": "Hello, world!",
  "client_id": "0987654321abcdef0987654321abcdef",
  "client_secret": "0987654321abcdef0987654321abcdef",
  "code": "0987654321abcdef0987654321abcdef"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "grant_type: `authorization_code`, `refresh_token` (string, required) - *MUST* have the value `authorization_code` or `refresh_token`.": {
      "type": "string"
    },
    "client_id": {
      "type": "string",
      "description": "the unique id issued by Cabify for the client application."
    },
    "client_secret": {
      "type": "string",
      "description": "the unique secret issued by Cabify for the client application."
    },
    "code": {
      "type": "string",
      "description": "the authorization code we got in the previous step."
    }
  },
  "required": [
    "client_id",
    "client_secret",
    "code"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "0987654321abcdef0987654321abcdef",
  "refresh_token": "0987654321abcdef0987654321abcdef"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token_type": {
      "type": "string",
      "description": "*ALWAYS* have the value `Bearer`"
    },
    "expires_in": {
      "type": "number",
      "description": "number of seconds until the authorization expires."
    },
    "access_token": {
      "type": "string",
      "description": "the authorization token."
    },
    "refresh_token": {
      "type": "string",
      "description": "a token we can use in the future to refresh an authorization that is about to expire."
    }
  },
  "required": [
    "token_type",
    "expires_in",
    "access_token",
    "refresh_token"
  ]
}

Users

Users

Get User Information
GET/api/v2/user

Retrieves the information of the authenticated user.

Example URI

GET /api/v2/user
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Accept-Language: en
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "avatar_url": "https://secure.gravatar.com/avatar/af276ab86f332e84bc3b0cfaee12b38b?r=pg&s=80&d=blank",
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@cabify.com",
  "mobile_cc": "+34",
  "mobile_num": "611111113",
  "locale": "es-ES"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "avatar_url": {
      "type": "string",
      "description": "User avatar URL"
    },
    "name": {
      "type": "string",
      "description": "User name"
    },
    "surname": {
      "type": "string",
      "description": "User surname"
    },
    "email": {
      "type": "string",
      "description": "User email"
    },
    "mobile_cc": {
      "type": "string",
      "description": "User mobile number prefix"
    },
    "mobile_num": {
      "type": "string",
      "description": "User mobile number prefix"
    },
    "locale": {
      "type": "string",
      "description": "User locale"
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json

Estimates

Estimate Journeys

Get Estimates
POST/api/v2/estimate

To get an estimate, start and end points need to be provided. If start_at time is provided, the journey will be considered as a reserved journey, reserved journeys needs to have a start_at some minutes in the future.

If you set the start_at attribute as null or ommit it, we will considered the current time as the start_at time and the journey start_type will be asap. In this case, each vehicle type will come with a new attribute called ETA. This attribute contains the information about the expected time (in seconds) a vehicle of that type will arrive. If the values of the attribute ETA are min:0 and max:999999, this means we aren’t able to predict the ETA for that vehicle type.

Example URI

POST /api/v2/estimate
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Accept-Language: en
Body
{
  "stops": [
    {
      "loc": [
        40.4169473,
        -3.7057172
      ],
      "name": "Puerta del Sol",
      "addr": "Plaza de la Puerta del Sol",
      "num": "s/n",
      "city": "Madrid",
      "country": "Spain",
      "instr": "Hello, world!",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "+34",
        "mobile_num": "611111113"
      }
    },
    {
      "loc": [
        40.4169473,
        -3.7057172
      ],
      "name": "Puerta del Sol",
      "addr": "Plaza de la Puerta del Sol",
      "num": "s/n",
      "city": "Madrid",
      "country": "Spain",
      "instr": "Hello, world!",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "+34",
        "mobile_num": "611111113"
      }
    }
  ],
  "start_at": "2022-12-30 22:59"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "stops": {
      "type": "array",
      "description": "A 2-tuple with the pick up and drop off locations."
    },
    "start_at": {
      "type": "string",
      "description": "The pick up datetime. It should follow the format: YYYY-MM-DD hh:mm. It should be in the local time of the pick up location."
    }
  },
  "required": [
    "stops",
    "start_at"
  ]
}
Response  200
HideShow

Returns an array of Estimates.

Some vehicle types, such as taxis, can not be estimated. In that case, the estimate will include the Vehicle Type details but the price-related fields will have null values (except when noted).

Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "vehicle_type": {
      "_id": "executive_id",
      "name": "Executive Class",
      "short_name": "Executive",
      "description": "A very large vehicle with comfortable seats",
      "icons": {
        "regular": "https://cabify.com/images/icons/vehicle_type/executive_27.png"
      },
      "icon": "executive",
      "service_type": "standard"
    },
    "total_price": 1234,
    "price_formatted": "12.34€",
    "currency": "EUR",
    "currency_symbol": "€",
    "eta": {
      "min": 100,
      "max": 1000,
      "formatted": ">2 min"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Request  Start point outside of Cabify regions
HideShow

If we request an estimate from outside the places we operate, a 404 error is returned. In this example, the start stop is in the Atlantic Ocean.

Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Body
{
  "stops": [
    {
      "loc": [
        0.1,
        0.1
      ]
    },
    {
      "loc": [
        40.522751,
        -3.890156
      ]
    }
  ],
  "start_at": "2015-12-23 15:09"
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "You provided incomplete information",
  "errors": {
    "some_attribute": [
      "Hello, world!",
      "is too small",
      "needs to be odd"
    ],
    "some_other": [
      "Hello, world!",
      "is required"
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error description"
    },
    "errors": {
      "type": "object",
      "properties": {
        "some_attribute": {
          "type": "array"
        },
        "some_other": {
          "type": "array"
        }
      },
      "description": "Per field error information. Keys are field names, values are arrays of strings with error messages for the field."
    }
  },
  "required": [
    "message"
  ]
}

Bookings

This resource allows booking and management of a future journey.

Make a booking

Make a booking
POST/api/v2/journey

This endpoint is meant to be used after receiving an estimate for a journey. The parameters used for the estimate can be reused and, additionally, the selector vehicle type needs to be provided.

It is also possible to book a Cabify without any previous estimate if you have been provided with a vehicle_type_id.

If you need to do a asap journey, you only need to set the start_at parameter as null, this will make we considered the start_at as the current time and the start_type of the journey as asap.

If you need to book a journey for person different from the one who belongs the Auth Token, you can specify its information using the rider attribute in the request body. In other case, you can just omit this attribute, and the journey will be create for the owner of the Auth Token.

Additionally, in order to allow cross-referencing of Cabify journeys and any internal system used by API clients, the optional property charge_code can be used. It will not be interpreted by Cabify, but will be present in the invoices (contact your sales representative if you need it to be required and/or follow some format). Another optional property can be used called reason, that gives a short explanation of why the rider/user is doing the journey (some companies may need aditional info apart from charge_code for understand employees journeys).

Cabify Delivery Service

Cabify also offers a delivery service which you can use on the API. To use the delivery service you should make a booking using a vehicle_type_id which belongs to a vehicle type called delivery or cabify express. You can get this id from the response of the estimate resource. Besides, you should fill the stop contact attributes (name, mobile_cc, mobile_num) which you can see in the request body of this request.

When you book a journey with a delivery vehicle type, the response of the booking will include an attribute service_type with value delivery. In other case, the value of this attribute will be standard.

Example URI

POST /api/v2/journey
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Body
{
  "stops": [
    {
      "loc": [
        40.4169473,
        -3.7057172
      ],
      "name": "Puerta del Sol",
      "addr": "Plaza de la Puerta del Sol",
      "num": "s/n",
      "city": "Madrid",
      "country": "Spain",
      "instr": "Hello, world!",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "+34",
        "mobile_num": "611111113"
      }
    }
  ],
  "start_at": "2022-12-30 22:59",
  "vehicle_type_id": "executive_id",
  "charge_code": "TAR987-654",
  "reason": "Is a bussiness trip",
  "rider": {
    "name": "John Doe",
    "phone_prefix": "+34",
    "phone_number": "555-1234",
    "email": "jdoe@example.com",
    "locale": "en"
  },
  "message": "Pick up at the red building next to the supermarket"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "stops": {
      "type": "array",
      "description": "An array with the pick up location (required) and drop off locations (optional)."
    },
    "start_at": {
      "type": "string",
      "description": "The pick up datetime. It should follow the format: YYYY-MM-DD hh:mm. It should be in the local time of the pick up location."
    },
    "vehicle_type_id": {
      "type": "string",
      "description": "The unique identifier of the selected vehicle type, as returned by the estimator."
    },
    "charge_code": {
      "type": "string",
      "description": "An optional code that will be displayed in the invoices generated by Cabify. Can be used to cross-reference the booking to internal data (such as a flight number reference, client id, etc…)."
    },
    "reason": {
      "type": "string",
      "description": "An optional reasong text that will be displayed in the invoices generated by Cabify. Can be used for giving extra info about why doing that journey."
    },
    "rider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Rider name"
        },
        "phone_prefix": {
          "type": "string",
          "description": "Country prefix for the rider's phone number"
        },
        "phone_number": {
          "type": "string",
          "description": "Rider's phone number"
        },
        "email": {
          "type": "string",
          "description": "Rider's contact email"
        },
        "locale": {
          "type": "string",
          "description": "Rider's locale. Used to generate the sms messages we send to the rider."
        }
      },
      "required": [
        "name"
      ],
      "description": "Optional information and contact details for the rider. Will allow the driver to contact her in case of any issues with the booking."
    },
    "message": {
      "type": "string",
      "description": "An optional string providing some useful information for the driver."
    }
  },
  "required": [
    "stops",
    "start_at",
    "vehicle_type_id",
    "rider"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "_id": "booking_id"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_id": {
      "type": "string",
      "description": "The unique id assigned to this booking."
    }
  },
  "required": [
    "_id"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json: charset=utf-8
Body
{
  "message": "You provided incomplete information",
  "errors": {
    "some_attribute": [
      "Hello, world!",
      "is too small",
      "needs to be odd"
    ],
    "some_other": [
      "Hello, world!",
      "is required"
    ]
  }
}
Schema
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error description"
    },
    "errors": {
      "type": "object",
      "properties": {
        "some_attribute": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "some_other": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "description": "Per field error information. Keys are field names, values are arrays of strings with error messages for the field."
    }
  },
  "required": [
    "message"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Retrieve booking information

Retrieve booking information
GET/api/v2/journey/{id}

For most uses, the (booking state)[#bookings-booking-state-get] is preferred.

Use this endpoint to retrieve the full information about a booking, such as pricing or the initially provided information when making a booking.

Example URI

GET /api/v2/journey/0987654321abcdef0987654321abcdef
URI Parameters
HideShow
id
string (required) Example: 0987654321abcdef0987654321abcdef

the id corresponding to the journey to be retrieved. Access controls will be aplied to ensure that the authenticated user can access the journey

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "stops": [
    {
      "loc": [
        40.4169473,
        -3.7057172
      ],
      "name": "Puerta del Sol",
      "addr": "Plaza de la Puerta del Sol",
      "num": "s/n",
      "city": "Madrid",
      "country": "Spain",
      "instr": "Hello, world!",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "+34",
        "mobile_num": "611111113"
      },
      "hit_at": "2022-12-30 22:59"
    },
    {
      "loc": [
        40.4169473,
        -3.7057172
      ],
      "name": "Puerta del Sol",
      "addr": "Plaza de la Puerta del Sol",
      "num": "s/n",
      "city": "Madrid",
      "country": "Spain",
      "instr": "Hello, world!",
      "contact": {
        "name": "John Doe",
        "mobile_cc": "+34",
        "mobile_num": "611111113"
      },
      "hit_at": "2022-12-30 22:59"
    }
  ],
  "start_at": "2022-12-30T21:59:00.000Z",
  "vehicle_type_id": "executive_id",
  "service_type": "standard",
  "rider": {
    "name": "John Doe",
    "phone_prefix": "+34",
    "phone_number": "555-1234",
    "email": "jdoe@example.com",
    "locale": "en"
  },
  "message": "Pick up at the red building next to the supermarket",
  "state": {
    "journey_id": "0987654321abcdef0987654321abcdef",
    "name": "reserve",
    "loc": [
      40.345041,
      -1.1185173
    ],
    "driver": {
      "id": "0987654321abcdef0987654321abcdef",
      "name": "Martín",
      "surname": "de la Cuadra",
      "mobile": "555-1234",
      "score": 4.8,
      "avatar_url": "https://cabify.com/drivers/123"
    },
    "vehicle": {
      "reg_plate": "1234CDF",
      "color": {
        "code": "white",
        "rgb": "FFFFFF"
      },
      "model": {
        "make": "Ford",
        "model": "Focus",
        "brand_icon": "https://cabify.com/vehicles/make/ford.png"
      }
    }
  },
  "distance": 10000,
  "duration": 600,
  "moving": 0,
  "stopped": 0,
  "public_url": "url of a public page from where the user can be follow the status of the journey",
  "prices": {
    "price_base": {
      "amount": 2095,
      "currency": "EUR",
      "currency_symbol": "€",
      "formatted": "20.95 €"
    },
    "price_extra": {
      "amount": 2095,
      "currency": "EUR",
      "currency_symbol": "€",
      "formatted": "20.95 €"
    },
    "price": {
      "amount": 2095,
      "currency": "EUR",
      "currency_symbol": "€",
      "formatted": "20.95 €"
    },
    "discount": {
      "amount": 2095,
      "currency": "EUR",
      "currency_symbol": "€",
      "formatted": "20.95 €"
    },
    "total": {
      "amount": 2095,
      "currency": "EUR",
      "currency_symbol": "€",
      "formatted": "20.95 €"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "stops": {
      "type": "array",
      "description": "An array with the pick up, pauses and drop off locations."
    },
    "start_at": {
      "type": "string",
      "description": "the UTC start at date in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.sTZD`."
    },
    "vehicle_type_id": {
      "type": "string",
      "description": "The unique identifier of the selected vehicle type, as returned by the estimator."
    },
    "service_type": {
      "type": "string",
      "description": "Service type of the journey. It can be standard or delivery."
    },
    "rider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Rider name"
        },
        "phone_prefix": {
          "type": "string",
          "description": "Country prefix for the rider's phone number"
        },
        "phone_number": {
          "type": "string",
          "description": "Rider's phone number"
        },
        "email": {
          "type": "string",
          "description": "Rider's contact email"
        },
        "locale": {
          "type": "string",
          "description": "Rider's locale. Used to generate the sms messages we send to the rider."
        }
      },
      "required": [
        "name"
      ],
      "description": "Optional information and contact details for the rider. Will allow the driver to contact her in case of any issues with the booking."
    },
    "message": {
      "type": "string",
      "description": "An optional string providing some useful information for the driver."
    },
    "state": {
      "type": "object",
      "properties": {
        "journey_id": {
          "type": "string",
          "description": "id of the Journey which the state belongs"
        },
        "name": {
          "type": "string",
          "enum": [
            "reserve",
            "hire",
            "hired",
            "arrived",
            "pick up",
            "drop off",
            "terminated",
            "no show",
            "not found",
            "missed",
            "rejected",
            "rider cancel",
            "driver cancel",
            "timeout"
          ]
        },
        "loc": {
          "type": "array",
          "description": "the Cabify position at the time of the update"
        },
        "driver": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "id of the Driver."
            },
            "name": {
              "type": "string",
              "description": "driver's given name."
            },
            "surname": {
              "type": "string",
              "description": "driver's family name."
            },
            "mobile": {
              "type": "string",
              "description": "the driver's phone number."
            },
            "score": {
              "type": "number",
              "description": "average driver rating in a 0 (awful) to 5 (perfect) range."
            },
            "avatar_url": {
              "type": "string",
              "description": "the url to the driver picture at 80x80 pixels."
            }
          },
          "description": "information about the driver"
        },
        "vehicle": {
          "type": "object",
          "properties": {
            "reg_plate": {
              "type": "string",
              "description": "vehicle's registration plate number"
            },
            "color": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "white",
                    "silver",
                    "gray",
                    "black",
                    "red",
                    "maroon",
                    "yellow",
                    "olive",
                    "lime",
                    "green",
                    "aqua",
                    "teal",
                    "blue",
                    "navy",
                    "fuchsia",
                    "purple",
                    "orange",
                    "gold"
                  ],
                  "description": "color code"
                },
                "rgb": {
                  "type": "string",
                  "description": "suggested rgb color to represent the given code"
                }
              },
              "description": "the vehicle color"
            },
            "model": {
              "type": "object",
              "properties": {
                "make": {
                  "type": "string",
                  "description": "Make name"
                },
                "model": {
                  "type": "string",
                  "description": "Model name"
                },
                "brand_icon": {
                  "type": "string",
                  "description": "url to the make icon, a 200x200 png image."
                }
              }
            }
          },
          "description": "information about the vehicle"
        }
      }
    },
    "distance": {
      "type": "number",
      "description": "Distance travelled in meters"
    },
    "duration": {
      "type": "number",
      "description": "Journey time in seconds from arrival to drop off"
    },
    "moving": {
      "type": "number",
      "description": "Distance moved over threshold speed"
    },
    "stopped": {
      "type": "number",
      "description": "Time stopped under threshold speed"
    },
    "public_url": {
      "type": "string"
    },
    "prices": {
      "type": "object",
      "properties": {
        "price_base": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "currency_symbol": {
              "type": "string"
            },
            "formatted": {
              "type": "string"
            }
          },
          "required": [
            "amount",
            "currency",
            "currency_symbol",
            "formatted"
          ],
          "description": "The price by distance and waiting time or the minimun price."
        },
        "price_extra": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "currency_symbol": {
              "type": "string"
            },
            "formatted": {
              "type": "string"
            }
          },
          "required": [
            "amount",
            "currency",
            "currency_symbol",
            "formatted"
          ],
          "description": "The additional price: toll, parking..."
        },
        "price": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "currency_symbol": {
              "type": "string"
            },
            "formatted": {
              "type": "string"
            }
          },
          "required": [
            "amount",
            "currency",
            "currency_symbol",
            "formatted"
          ],
          "description": "The sum of price_base and price_extra."
        },
        "discount": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "currency_symbol": {
              "type": "string"
            },
            "formatted": {
              "type": "string"
            }
          },
          "required": [
            "amount",
            "currency",
            "currency_symbol",
            "formatted"
          ],
          "description": "The discount applied in the booking (vouchers, special zones or balances for the user)."
        },
        "total": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "currency_symbol": {
              "type": "string"
            },
            "formatted": {
              "type": "string"
            }
          },
          "required": [
            "amount",
            "currency",
            "currency_symbol",
            "formatted"
          ],
          "description": "The subtraction between price and discount."
        }
      },
      "required": [
        "price_base",
        "price",
        "total"
      ]
    }
  },
  "required": [
    "stops",
    "start_at",
    "vehicle_type_id",
    "rider",
    "state"
  ]
}

Booking State

Every journey have a state which track in what point of the ride is it.

  • reserve - Journey is reserved

  • hire - Journey is searching for a driver

  • hired - Journey has been assigned a driver

  • arrived - Car is at the pick up point

  • pick up - The rider is on the car

  • drop off - Sent by the driver to indicate that they have arrived.

  • terminated - Journey has been successfully terminated and requires no further action.

  • no show - Journey cancelled because the rider did not show at the pick up point

  • not found - No drivers have been found to perform the journey.

  • missed - A driver doesn’t accept the journey.

  • rejected - The driver clicked the reject button for journey.

  • rider cancel - Journey cancelled by request of the API

  • driver cancel - Journey cancelled by request of the driver or Cabify admin

  • timeout - Ongoing journey without recent information from the driver (typically on tunnels)

Cancel booking

Cancel booking
POST/api/v2/journey/{id}/state

Any previously booked journey can be canceled using its _id field, as long as:

  • The journey has not started yet

  • It has been created by the same API user

Example URI

POST /api/v2/journey/0987654321abcdef0987654321abcdef/state
URI Parameters
HideShow
id
string (required) Example: 0987654321abcdef0987654321abcdef

the id corresponding to the journey that is to be canceled. It must be in the future and owned by the API user identified by the oauth token.

Request
HideShow

Changes the booking state to the provided name.

Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Body
{
  "name": "rider cancel"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "enum": [
        "rider cancel"
      ]
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "journey_id": "0987654321abcdef0987654321abcdef",
  "name": "reserve",
  "loc": [
    40.345041,
    -1.1185173
  ],
  "driver": {
    "id": "0987654321abcdef0987654321abcdef",
    "name": "Martín",
    "surname": "de la Cuadra",
    "mobile": "555-1234",
    "score": 4.8,
    "avatar_url": "https://cabify.com/drivers/123"
  },
  "vehicle": {
    "reg_plate": "1234CDF",
    "color": {
      "code": "white",
      "rgb": "FFFFFF"
    },
    "model": {
      "make": "Ford",
      "model": "Focus",
      "brand_icon": "https://cabify.com/vehicles/make/ford.png"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "journey_id": {
      "type": "string",
      "description": "id of the Journey which the state belongs"
    },
    "name": {
      "type": "string",
      "enum": [
        "reserve",
        "hire",
        "hired",
        "arrived",
        "pick up",
        "drop off",
        "terminated",
        "no show",
        "not found",
        "missed",
        "rejected",
        "rider cancel",
        "driver cancel",
        "timeout"
      ]
    },
    "loc": {
      "type": "array",
      "description": "the Cabify position at the time of the update"
    },
    "driver": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the Driver."
        },
        "name": {
          "type": "string",
          "description": "driver's given name."
        },
        "surname": {
          "type": "string",
          "description": "driver's family name."
        },
        "mobile": {
          "type": "string",
          "description": "the driver's phone number."
        },
        "score": {
          "type": "number",
          "description": "average driver rating in a 0 (awful) to 5 (perfect) range."
        },
        "avatar_url": {
          "type": "string",
          "description": "the url to the driver picture at 80x80 pixels."
        }
      },
      "description": "information about the driver"
    },
    "vehicle": {
      "type": "object",
      "properties": {
        "reg_plate": {
          "type": "string",
          "description": "vehicle's registration plate number"
        },
        "color": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "white",
                "silver",
                "gray",
                "black",
                "red",
                "maroon",
                "yellow",
                "olive",
                "lime",
                "green",
                "aqua",
                "teal",
                "blue",
                "navy",
                "fuchsia",
                "purple",
                "orange",
                "gold"
              ],
              "description": "color code"
            },
            "rgb": {
              "type": "string",
              "description": "suggested rgb color to represent the given code"
            }
          },
          "description": "the vehicle color"
        },
        "model": {
          "type": "object",
          "properties": {
            "make": {
              "type": "string",
              "description": "Make name"
            },
            "model": {
              "type": "string",
              "description": "Model name"
            },
            "brand_icon": {
              "type": "string",
              "description": "url to the make icon, a 200x200 png image."
            }
          }
        }
      },
      "description": "information about the vehicle"
    }
  }
}
Request  with invalid state name
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Body
{
  "name": "invalid"
}
Response  400
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "You provided incomplete information",
  "errors": {
    "some_attribute": [
      "Hello, world!",
      "is too small",
      "needs to be odd"
    ],
    "some_other": [
      "Hello, world!",
      "is required"
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error description"
    },
    "errors": {
      "type": "object",
      "properties": {
        "some_attribute": {
          "type": "array"
        },
        "some_other": {
          "type": "array"
        }
      },
      "description": "Per field error information. Keys are field names, values are arrays of strings with error messages for the field."
    }
  },
  "required": [
    "message"
  ]
}

Check booking state

Check booking state
GET/api/v2/journey/{id}/state

Example URI

GET /api/v2/journey/0987654321abcdef0987654321abcdef/state
URI Parameters
HideShow
id
string (required) Example: 0987654321abcdef0987654321abcdef

the id of the journey whose state is to be checked.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer YOUR_AUTH_TOKEN
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "journey_id": "0987654321abcdef0987654321abcdef",
  "name": "reserve",
  "loc": [
    40.345041,
    -1.1185173
  ],
  "driver": {
    "id": "0987654321abcdef0987654321abcdef",
    "name": "Martín",
    "surname": "de la Cuadra",
    "mobile": "555-1234",
    "score": 4.8,
    "avatar_url": "https://cabify.com/drivers/123"
  },
  "vehicle": {
    "reg_plate": "1234CDF",
    "color": {
      "code": "white",
      "rgb": "FFFFFF"
    },
    "model": {
      "make": "Ford",
      "model": "Focus",
      "brand_icon": "https://cabify.com/vehicles/make/ford.png"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "journey_id": {
      "type": "string",
      "description": "id of the Journey which the state belongs"
    },
    "name": {
      "type": "string",
      "enum": [
        "reserve",
        "hire",
        "hired",
        "arrived",
        "pick up",
        "drop off",
        "terminated",
        "no show",
        "not found",
        "missed",
        "rejected",
        "rider cancel",
        "driver cancel",
        "timeout"
      ]
    },
    "loc": {
      "type": "array",
      "description": "the Cabify position at the time of the update"
    },
    "driver": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the Driver."
        },
        "name": {
          "type": "string",
          "description": "driver's given name."
        },
        "surname": {
          "type": "string",
          "description": "driver's family name."
        },
        "mobile": {
          "type": "string",
          "description": "the driver's phone number."
        },
        "score": {
          "type": "number",
          "description": "average driver rating in a 0 (awful) to 5 (perfect) range."
        },
        "avatar_url": {
          "type": "string",
          "description": "the url to the driver picture at 80x80 pixels."
        }
      },
      "description": "information about the driver"
    },
    "vehicle": {
      "type": "object",
      "properties": {
        "reg_plate": {
          "type": "string",
          "description": "vehicle's registration plate number"
        },
        "color": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "white",
                "silver",
                "gray",
                "black",
                "red",
                "maroon",
                "yellow",
                "olive",
                "lime",
                "green",
                "aqua",
                "teal",
                "blue",
                "navy",
                "fuchsia",
                "purple",
                "orange",
                "gold"
              ],
              "description": "color code"
            },
            "rgb": {
              "type": "string",
              "description": "suggested rgb color to represent the given code"
            }
          },
          "description": "the vehicle color"
        },
        "model": {
          "type": "object",
          "properties": {
            "make": {
              "type": "string",
              "description": "Make name"
            },
            "model": {
              "type": "string",
              "description": "Model name"
            },
            "brand_icon": {
              "type": "string",
              "description": "url to the make icon, a 200x200 png image."
            }
          }
        }
      },
      "description": "information about the vehicle"
    }
  }
}

Webhooks

Booking status updates

Booking status changes can be notified through a webhook. At the moment, you can configure the URL where the URL will be POSTing the updates by contacting customer support.

The given URL will be invoked with the webhook url sending the same information as the [Check booking status] response but using x-www-form-urlencoded format.

Generated by aglio on 20 Nov 2017