Developers
API reference
Every endpoint of the Public Booking API, generated from the API's code. For keys, errors and conventions, see the API overview.
Chauffeur Circle Public Booking API · version 0.0.1 · openapi.json
- GET /v1/bookings
- POST /v1/bookings
- GET /v1/bookings/{booking}
- POST /v1/bookings/{booking}/cancel
- POST /v1/quotes
- POST /v1/route
- GET /v1/widget/config
GET /v1/bookings
List bookings (secret key)
For your own server, with a secret key. Filters: status, payment_status, from / to
(pickup dates in the operator's timezone), updated_since (ISO 8601). Newest pickups last.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | BookingStatus | null | |
payment_status | query | BookingPaymentStatus | null | |
from | query | string | null (date) | |
to | query | string | null (date) | |
updated_since | query | string | null (date-time) | |
per_page | query | integer | null |
Responses
200Paginated set ofBookingResource422Validation error
POST /v1/bookings
Create a booking
Books a vehicle from a quote. Requires an Idempotency-Key header. The price is recalculated on
the server from the stored quote. For priced vehicles the booking waits for a card
(status: pending_card): show the payment_session.frame_url in an iframe. Quote-only
vehicles create a quote request (quote_request: true) and no payment session.
Request body
| Field | Type | Description |
|---|---|---|
quote_idrequired | string (uuid) | The id of a quote from POST /v1/quotes. The price is recalculated from it on the server. |
vehicle_type_idrequired | integer | |
customerrequired | object | |
customer.first_namerequired | string | |
customer.last_namerequired | string | |
customer.emailrequired | string (email) | |
customer.phonerequired | string | |
passenger | object | Only when someone else travels. |
passenger.first_name | string | |
passenger.last_name | string | |
passenger.phone | string | null | |
passenger.email | string | null (email) | |
gratuity_bps | integer | null | |
extras | object[] | Replaces the extras chosen on the quote. |
extras[].idrequired | integer | |
extras[].quantityrequired | integer | |
notes | string | null | |
flight_number | string | null | |
airline | string | null | |
terms_accepted | "yes" | "on" | "1" | 1 | "true" | true | |
source | "widget" | "custom_form" | "sdk" | null | |
utm | object | |
utm.source | string | null | |
utm.medium | string | null | |
utm.campaign | string | null | |
utm.term | string | null | |
utm.content | string | null | |
utm.referrer | string | null |
Responses
201PublicBookingResource422Validation error
GET /v1/bookings/{booking}
Look up a booking
For passengers: the booking reference and the email address used to book. With a secret key the email is not needed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
bookingrequired | path | string | The booking reference |
email | query | string | null (email) | Secret keys (the operator's own server) do not need the passenger's email. |
reason | query | string | null |
Responses
200PublicBookingResource404Not found422Validation error
POST /v1/bookings/{booking}/cancel
Cancel a booking
For passengers: free until the policy's free-cancellation time, after that the late-cancellation
fee applies (see cancellation in the booking). With a secret key the email is not needed; the
passenger's policy still applies.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
bookingrequired | path | string | The booking reference |
Request body
| Field | Type | Description |
|---|---|---|
email | string | null (email) | Secret keys (the operator's own server) do not need the passenger's email. |
reason | string | null |
Responses
200PublicBookingResource404Not found422Validation error
POST /v1/quotes
Get a quote
Prices the trip for every vehicle type: price lines and totals in cents, plus available and a
reason (capacity or fully_booked) when a vehicle cannot take the trip. Quote-only vehicles
have quote_only: true and no price. The quote is valid until expires_at; book with its id.
Request body
| Field | Type | Description |
|---|---|---|
service_typerequired | ServiceType | |
pickuprequired | object | A location is an airport code, or an address with coordinates. |
pickup.airport | string | null | |
pickup.address | string | null | |
pickup.lat | number | null | |
pickup.lng | number | null | |
pickup.place_id | string | null | |
dropoff | object | |
dropoff.airport | string | null | |
dropoff.address | string | null | |
dropoff.lat | number | null | |
dropoff.lng | number | null | |
dropoff.place_id | string | null | |
stops | object[] | |
stops[].addressrequired | string | |
stops[].latrequired | number | |
stops[].lngrequired | number | |
stops[].place_id | string | null | |
pickup_atrequired | string | ISO-8601. Without an offset it is read in the operator's timezone. |
hours | number | null | |
passengersrequired | integer | |
luggage | integer | null | |
gratuity_bps | integer | null | |
extras | object[] | |
extras[].idrequired | integer | |
extras[].quantityrequired | integer |
Responses
201QuoteResource422Validation error
POST /v1/route
Preview a route
The driving route between a pickup and a drop-off, with any stops, for showing on a map before
asking for a date and prices. polyline is a Google encoded polyline, or null when the distance
is only an estimate.
Request body
| Field | Type | Description |
|---|---|---|
pickuprequired | object | A location is an airport code, or an address with coordinates. |
pickup.airport | string | null | |
pickup.address | string | null | |
pickup.lat | number | null | |
pickup.lng | number | null | |
pickup.place_id | string | null | |
dropoffrequired | object | |
dropoff.airport | string | null | |
dropoff.address | string | null | |
dropoff.lat | number | null | |
dropoff.lng | number | null | |
dropoff.place_id | string | null | |
stops | object[] | |
stops[].addressrequired | string | |
stops[].latrequired | number | |
stops[].lngrequired | number | |
stops[].place_id | string | null |
Responses
200422Validation error
GET /v1/widget/config
Widget configuration
Branding, services, airports, extras, booking rules, policy texts, theme, the embed modes the operator's plan allows, Square settings for the payment frame, and whether payments are ready.
Responses
200