Chauffeur Circle Docs

Developers

API overview

The Public Booking API (https://api.chauffeurcircle.com/v1) powers the widget, the SDK and your own integrations. The full list of endpoints and fields is in the API reference, generated from the code.

Keys and authentication

Key Prefix Where Header
Publishable test cc_pk_test_ Websites; also localhost, 127.0.0.1, *.pages.dev X-Chauffeur-Circle-Key: cc_pk_test_…
Publishable live cc_pk_live_ Only the domains listed on the key X-Chauffeur-Circle-Key: cc_pk_live_…
Secret Business cc_sk_ Your server only Authorization: Bearer cc_sk_…
  • Publishable keys check the request's Origin (or Referer) against the key's domains. Wildcards like *.yourlimo.com work.
  • Secret keys are refused when the request has an Origin header, so they cannot be used from a browser by mistake.
  • Create, roll (replace) and revoke keys in API keys. Rolling gives a new key and stops the old one.
curl https://api.chauffeurcircle.com/v1/bookings?status=new \
  -H "Authorization: Bearer cc_sk_…"

Endpoints

Method Path What it does
GET /v1/widget/config Your branding, services, airports, extras, rules, policies and theme
POST /v1/quotes Prices for a trip, for each vehicle
POST /v1/bookings Book a quoted vehicle; returns a payment session
GET /v1/bookings/{reference} One booking (publishable keys: with ?email=)
POST /v1/bookings/{reference}/cancel Cancel by your policy (publishable keys: with email)
GET /v1/bookings List and filter bookings (secret key only)

Conventions

  • Money is in integer cents (11455 = $114.55); percentages are in basis points (2000 = 20%).
  • Times are ISO 8601. A pickup_at without an offset is read in your time zone; responses include the offset.
  • JSON in and out. Send Content-Type: application/json.

Idempotency

Every POST accepts an Idempotency-Key header (any unique string, such as a UUID). POST /v1/bookings requires it. Sending the same key again within 24 hours returns the first response instead of creating a second booking.

Error Meaning
idempotency_key_reused The key was used with a different request body
idempotency_in_progress The first request with this key is still running; retry shortly

Errors

Errors always have the same shape:

{ "error": { "code": "validation_failed", "message": "The given data was invalid.", "fields": { "customer.phone": ["Enter a valid phone number."] } } }
Code HTTP What to do
unauthenticated 401 Missing or wrong key
origin_not_allowed 403 Add this website's domain to the key
forbidden 403 The key cannot do this (for example a publishable key listing bookings)
plan_limit 403 Your plan does not include this; feature says which
booking_unavailable 403 Online booking is paused; show support_phone
payments_not_ready 403 Square is not connected yet
validation_failed 422 Fix the fields listed in fields
quote_expired 410 Get a new quote (quotes last 30 minutes)
quote_not_found 404 Unknown quote id
vehicle_unavailable 409 The vehicle was booked meanwhile; pick another
not_found 404 Unknown booking, or wrong email
invalid_state 409 The booking cannot do this now (for example cancelling a completed ride)
card_declined 402 The card was refused; the passenger can try another
session_expired 410 The payment link expired
rate_limited 429 Slow down; see Retry-After
server_error 500 Try again; contact us if it continues

Rate limits

Key Limit
Publishable 60 requests a minute per key and visitor IP; new bookings 10 a minute
Secret 300 requests a minute per key

Limited responses are 429 rate_limited with a Retry-After header.

OpenAPI

The machine-readable description is at https://api.chauffeurcircle.com/v1/openapi.json. Import it into Postman, Insomnia or a code generator.