SnapCar API Documentation

This document provides guidelines on how to access and use the SnapCar API, and is intended to be used alongside the reference documentation describing each endpoint. You can find it here: developer.snapcar.com/reference

Authentication

After registering as a SnapCar partner, you will be given an api id and secret, which you can use to identify yourself and access SnapCar endpoints that require a "partner" level authorization.

However, most endpoints require a "user" level authorization, such as creating a new booking, or accessing the booking history for this user. In order to access them, you will first need to obtain a user token.

Obtaining a user token

In order to obtain a user token, you need to follow a three-step process.

Step 1: Login form

To start the login procedure, you need to redirect the user to the following address: https://account.snapcar.com/login?api_id=YOUR_API_ID&redirect_url=YOUR_REDIRECT_URL

Parameter Description
api_id Your api id
redirect_url A endpoint we will call after the login is complete

The user will be invited to log in, or to create a new account if he hasn't already.

Step 2: Redirect

Once the login procedure is complete, we will call the endpoint you provided in the redirect_urlparameter.

GET https://your-redirect-uri/?status=ok&login_code=CODE
Parameter Description
status The request status: ok if the user accepted to log in, or access_denied if the user cancelled the login process.
login_code Only avalaible on status ok. Use this code to obtain the user token in step 3.

Step 3: Request the token

Use the /login_requests/{login_code} endpoint to obtain the user's identity and access token. See the reference documentation for more information about this endpoint.

Managing the user token

The provided token has an expiry date, after which you will need to ask the user to log in again. However, the token can be invalidated before its expiry date:

  • The user can invalidate a token at any moment
  • Another login request for the same user, and same api id will invalidate any previous token for this user. If you have several applications that require a SnapCar access, you may consider asking for several api ids.

When using the token to access a resource, any 403 Forbidden should be interpreted as an invalid token, and you are required to ask the user to log in again to SnapCar.

User access status

Each user must have registered a valid payment method in order to book a SnapCar. This is indicated by the status property of the UserDetails payload

Status property Description
booking_allowed The user has a valid payment method. Booking is possible.
booking_not_allowed The user has no registered payment method, or it has been invalidated. The user will have to register a new payment method before continuing. See the Register a payment method section.
suspended The user's account has been suspended. They will not be able to book, and are required to contact us at contact@snapcar.com to settle the issue.

Register a payment method

When the logged in user has the booking_not_allowed status, you can ask them to register a new payment method and proceed with the booking. You will need to redirect the user to this secure page: https://account.snapcar.com/card?token=TOKEN&redirect_url=YOUR_REDIRECT_URL

Parameter Description
token The current token for the user
redirect_url A endpoint we will call after a new payment method has been added

Booking procedure

Snapcar allows you to book immediately, or for a later date. Two pricing methods are supported: you can ask beforehands for a guaranteed price for a given trip, or default to our "pay as you go" pricing.

Service classes

Snapcar may provide several service classes depending on the location. In Paris, these services include "Classic", "Executive" and "Van" offers. You must use the info/service_classes endpoint to obtain the available services at your location. The services classes remain the same across a given region (for example Paris and Ile-De-France), so you don't need to refresh it at every address change.

Availability information

You can poll for the service's availability at a given location by using the info/eta endpoint. You will get an availability result for each service class in the same query. Check the status property to know if the service is currently available, then the eta property for an estimate of the approach time. See the reference documentation for this endpoint for further information.

Make a booking request

Simple booking procedure

The bookings POST endpoint allows you to send a request for a "pay as you go" booking. The minimum required settings are described below.

Parameter Description
token The current user's access token
rider_id The id of the rider making the booking request
start_location[lat] Starting location latitude
start_location[lng] Starting location longitude
start_location[address][street] Street/Name component of the address
start_location[address][city] City name of the address
service_class_id The id of the requested service class

We require that you provide an actual address alongside the coordinates, in order to avoid geocoding errors.

Booking for a later date

In order to book for a later date, you need to provide an additional parameter.

Parameter Description
date The UNIX timestamp of the required pickup date

Please be mindful of the end user's current timezone when obtaining the timestamp from the input date. All date fields displayed to the user should be formatted using the start location timezone, so make sure you don't forget to take into account any offset that may occur from the user's being in a different timezone. For rides in Ile-de-France, this is the Europe/Paris timezone.

Alternatively, you can provide a timezone regional identifier (such as 'Europe/Paris'), and we'll take care of the process ourselves.

Provide a fixed price

You can provide a fixed price in advance for a given trip. The user can then see and accept the price before booking. This require a two-step process: * A first query is used to get the price for the required trip * Another query is used to accept the price.

Get a booking price

The bookings/prices POST endpoint is used to obtain a price for a given trip. The information required is similar to the bookings endpoint, with the addition of the destination. See the reference documentation for additional parameters.

Parameter Description
token The current user's access token
rider_id The id of the rider making the booking request
start_location[lat] Starting location latitude
start_location[lng] Starting location longitude
start_location[address][street] Street/Name component of the address
start_location[address][city] City name of the address
end_location[lat] End location latitude
end_location[lng] End location longitude
end_location[address][street] Street/Name component of the destination address
end_location[address][city] City name of the destination address

The response payload will contain a price for every available service class. Just like with the simple booking procedure, you can provide a date parameter, if the booking is for later. We suggest you automatically propose a fixed price to the end user whenever they provide a destination.

Each price confirmation is valid for a few minutes. An expiry date is provided with the payload. You will need to call the endpoint again to obtain a new price confirmation afterwards. Note that the provided price may be different from the previous request.

Confirm a price

Use the bookings/prices/{id}/confirm POST endpoint to accept the price and create a booking with the information provided.

Additional options

SnapCar aims to provide the best possible experience for the end user. Several parameters are available to provide additional information and improve the user experience.

Nameboard

The user can require our drivers to wait for them at the start location, with a nameboard. Simply the nameboard parameter to 1 in the bookings or bookings/prices requests. Please note that this option can be charged an additional fee. The prices provided by the bookings/prices endpoint include this fee.

Meeting point

For several locations such as airports or stations, we provide a set of specific "meeting points" to facilitate the pickup.

The info/meeting_points endpoint allow you to check if you should ask the user to select a meeting point. The main elements of the response are described below. Each text property contains a french and english translation. See the reference documentation for more details:

Property Description
name The name of the area (example: Aéroport Charles-de-Gaulle)
menu_name How the input field for the meeting point should be named (example: Terminal)
selection_required If set to true, we require you provide a meeting point
meeting_points A list of selections items, if the nameboard option is not selected
meeting_points_nameboard A list of selections items, if the nameboard option is selected

As you can see, we provide two lists, depending on whether the nameboard option is selected or not.

You can then provide a meeting_point parameter in the bookings or bookings/prices/{id}/confirm requests, with the id of the selected meeting point.

Additional information

The additional_info parameter in the bookings or bookings/prices/{id}/confirm requests, can be used to forward to the driver any additional information the user may think necessary, such as details on the pickup location or special requests.

Managing Bookings

Once a booking has been successfully created, you will receive a payload containing its unique ID. You can use the bookings/{id} GET endpoint to follow the booking's progress. See the reference documentation for a description of all the information available.

Booking lifecycle

From its creation to its end, the booking will pass through several different statuses, described below. Depending on the current status, some properties of the booking will not be available.

Status Description
pending The booking has been successfully created
going_to_get A driver has been dispatched and is on their way to pick up the user. Driver information becomes available in the booking payload.
driver_waiting The driver has arrived to the pickup location and is waiting for the user
on_board The user is on board.
ride_ended The booking has been successfully completed.
cancelled The booking has been cancelled. The cancel_reason property will provide additional information.

Cancelling a booking

You can use the bookings/{id}/cancel POST endpoint to cancel a booking. Be careful, as this can be charged to the user.

Billing information

The detailled payload for a booking that has reached the ride_ended status or has been cancelled and charge may provide billing information. Please note however, that it may take up to an hour after the end of the booking before it becomes available.

The available information is described below.

Property Description
billed_amount The total, tax inclusive, billed amount for the booking. This can be different from the initial fixed price, which doesn't contain waiting fees or promotions.
vat_amount The total VAT amount
tip The additional tip the user has chosen to give the driver
documents A list of billing documents. These include bills, as well as any credit note that are associated with the booking. An url property is provided, to download the document.

Getting the users bookings

The bookings GET endpoint will return a summary of all the incoming bookings for the connected user. See the reference documentation for more information

The bookings/history GET endpoint acts similarly for past bookings. Uncharged cancelled bookings will not be displayed.

Annex: error codes

Below is a list of error codes that can be provided in the error property of the payload returned with a 400 status code.

General errors

These codes can be returned from any endpoint.

Error code Description
invalid_request Some parameters are missing or badly formatted. An additional details property may be provided, listing the erroneous fields.
other An unexpected error has occured

Booking errors

These errors can be returned from any endpoint used in the booking process.

Error code Description
no_service The start location is located outside of our service zone.
account_suspended The user's account has been suspended. The booking cannot be completed
no_payment_method The user has not provided any valid payment method. The booking cannot be completed

Booking for now

These errors can be returned when booking for now

Error code Description
no_driver No driver is available for the required service class. You may try with another service class

Booking for later

Error code Description
insufficient_delay The required pickup date is too close. We require at least a 1 hour delay
too_close_from_another The current user has already another booking planned for the same date
timeframe_unavailable Planned bookings are not available for the required date.
service_unavailable Planned bookings are not available for the required service class.

Confirming a fixed price

Error code Description
confirmation_expired You are beyond the give price confirmation's expiry date

Getting cancellation price

Error code Description
cannot_cancel The booking cannot be cancelled, because the ride has already started.

Annex: cancellation reasons

This lists the possible values of the cancellation_reason property of a cancelled booking

Cancellation reason Description
rider_cancellation The booking has been cancelled by the rider, and not charged
rider_cancellation_charged The booking has been cancelled by the rider, and has been charged a cancellation fee.
system_cancellation The booking has been cancelled by SnapCar.
system_cancellation_charged The booking has been cancelled by SnapCar, and charged.
no_driver No driver was available for dispatch.