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(orReferer) against the key's domains. Wildcards like*.yourlimo.comwork. - Secret keys are refused when the request has an
Originheader, 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_atwithout 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.