Chauffeur Circle Docs

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

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

NameInTypeDescription
statusqueryBookingStatus | null
payment_statusqueryBookingPaymentStatus | null
fromquerystring | null (date)
toquerystring | null (date)
updated_sincequerystring | null (date-time)
per_pagequeryinteger | null

Responses

  • 200 Paginated set of BookingResource
  • 422 Validation 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

FieldTypeDescription
quote_idrequiredstring (uuid)The id of a quote from POST /v1/quotes. The price is recalculated from it on the server.
vehicle_type_idrequiredinteger
customerrequiredobject
customer.first_namerequiredstring
customer.last_namerequiredstring
customer.emailrequiredstring (email)
customer.phonerequiredstring
passengerobjectOnly when someone else travels.
passenger.first_namestring
passenger.last_namestring
passenger.phonestring | null
passenger.emailstring | null (email)
gratuity_bpsinteger | null
extrasobject[]Replaces the extras chosen on the quote.
extras[].idrequiredinteger
extras[].quantityrequiredinteger
notesstring | null
flight_numberstring | null
airlinestring | null
terms_accepted"yes" | "on" | "1" | 1 | "true" | true
source"widget" | "custom_form" | "sdk" | null
utmobject
utm.sourcestring | null
utm.mediumstring | null
utm.campaignstring | null
utm.termstring | null
utm.contentstring | null
utm.referrerstring | null

Responses

  • 201 PublicBookingResource
  • 422 Validation 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

NameInTypeDescription
bookingrequiredpathstringThe booking reference
emailquerystring | null (email)Secret keys (the operator's own server) do not need the passenger's email.
reasonquerystring | null

Responses

  • 200 PublicBookingResource
  • 404 Not found
  • 422 Validation 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

NameInTypeDescription
bookingrequiredpathstringThe booking reference

Request body

FieldTypeDescription
emailstring | null (email)Secret keys (the operator's own server) do not need the passenger's email.
reasonstring | null

Responses

  • 200 PublicBookingResource
  • 404 Not found
  • 422 Validation 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

FieldTypeDescription
service_typerequiredServiceType
pickuprequiredobjectA location is an airport code, or an address with coordinates.
pickup.airportstring | null
pickup.addressstring | null
pickup.latnumber | null
pickup.lngnumber | null
pickup.place_idstring | null
dropoffobject
dropoff.airportstring | null
dropoff.addressstring | null
dropoff.latnumber | null
dropoff.lngnumber | null
dropoff.place_idstring | null
stopsobject[]
stops[].addressrequiredstring
stops[].latrequirednumber
stops[].lngrequirednumber
stops[].place_idstring | null
pickup_atrequiredstringISO-8601. Without an offset it is read in the operator's timezone.
hoursnumber | null
passengersrequiredinteger
luggageinteger | null
gratuity_bpsinteger | null
extrasobject[]
extras[].idrequiredinteger
extras[].quantityrequiredinteger

Responses

  • 201 QuoteResource
  • 422 Validation 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

FieldTypeDescription
pickuprequiredobjectA location is an airport code, or an address with coordinates.
pickup.airportstring | null
pickup.addressstring | null
pickup.latnumber | null
pickup.lngnumber | null
pickup.place_idstring | null
dropoffrequiredobject
dropoff.airportstring | null
dropoff.addressstring | null
dropoff.latnumber | null
dropoff.lngnumber | null
dropoff.place_idstring | null
stopsobject[]
stops[].addressrequiredstring
stops[].latrequirednumber
stops[].lngrequirednumber
stops[].place_idstring | null

Responses

  • 200
  • 422 Validation 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