{"openapi":"3.1.2","info":{"title":"Chauffeur Circle Public Booking API","version":"0.0.1","description":"Use a publishable key (`X-Chauffeur-Circle-Key: cc_pk_...`) from allowed websites, or a secret key (`Authorization: Bearer cc_sk_...`) from your server. Errors use `{ \"error\": { \"code\", \"message\", \"fields\" } }`."},"servers":[{"url":"https:\/\/docs.chauffeurcircle.com\/v1"}],"security":[{"publishableKey":[]}],"paths":{"\/bookings":{"post":{"operationId":"v1.bookings.store","description":"Books a vehicle from a quote. Requires an `Idempotency-Key` header. The price is recalculated on\nthe server from the stored quote. For priced vehicles the booking waits for a card\n(`status: pending_card`): show the `payment_session.frame_url` in an iframe. Quote-only\nvehicles create a quote request (`quote_request: true`) and no payment session.","summary":"Create a booking","tags":["Booking"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateBookingRequest"}}}},"responses":{"201":{"description":"`PublicBookingResource`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/PublicBookingResource"},"payment_session":{"type":["object","null"],"properties":{"id":{"type":"string"},"frame_url":{"type":"string"},"expires_at":{"type":"string"}},"required":["id","frame_url","expires_at"]}},"required":["data","payment_session"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}},"get":{"operationId":"v1.bookings.index","description":"For your own server, with a secret key. Filters: `status`, `payment_status`, `from` \/ `to`\n(pickup dates in the operator's timezone), `updated_since` (ISO 8601). Newest pickups last.","summary":"List bookings (secret key)","tags":["Booking"],"parameters":[{"name":"status","in":"query","schema":{"anyOf":[{"$ref":"#\/components\/schemas\/BookingStatus"},{"type":"null"}]}},{"name":"payment_status","in":"query","schema":{"anyOf":[{"$ref":"#\/components\/schemas\/BookingPaymentStatus"},{"type":"null"}]}},{"name":"from","in":"query","schema":{"type":["string","null"],"format":"date"}},{"name":"to","in":"query","schema":{"type":["string","null"],"format":"date"}},{"name":"updated_since","in":"query","schema":{"type":["string","null"],"format":"date-time"}},{"name":"per_page","in":"query","schema":{"type":["integer","null"],"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated set of `BookingResource`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/BookingResource"}},"links":{"type":"object","properties":{"first":{"type":["string","null"]},"last":{"type":["string","null"]},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["first","last","prev","next"]},"meta":{"type":"object","properties":{"current_page":{"type":"integer","minimum":1},"from":{"type":["integer","null"],"minimum":1},"last_page":{"type":"integer","minimum":1},"links":{"type":"array","description":"Generated paginator links.","items":{"type":"object","properties":{"url":{"type":["string","null"]},"label":{"type":"string"},"active":{"type":"boolean"}},"required":["url","label","active"]}},"path":{"type":["string","null"],"description":"Base path for paginator generated URLs."},"per_page":{"type":"integer","description":"Number of items shown per page.","minimum":0},"to":{"type":["integer","null"],"description":"Number of the last item in the slice.","minimum":1},"total":{"type":"integer","description":"Total number of items being paginated.","minimum":0}},"required":["current_page","from","last_page","links","path","per_page","to","total"]}},"required":["data","links","meta"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/bookings\/{booking}":{"get":{"operationId":"v1.bookings.show","description":"For passengers: the booking reference and the email address used to book. With a secret key\nthe email is not needed.","summary":"Look up a booking","tags":["Booking"],"parameters":[{"name":"booking","in":"path","required":true,"description":"The booking reference","schema":{"type":"string"}},{"name":"email","in":"query","description":"Secret keys (the operator's own server) do not need the passenger's email.","schema":{"type":["string","null"],"format":"email","maxLength":255}},{"name":"reason","in":"query","schema":{"type":["string","null"],"maxLength":500}}],"responses":{"200":{"description":"`PublicBookingResource`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/PublicBookingResource"}},"required":["data"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/bookings\/{booking}\/cancel":{"post":{"operationId":"v1.bookings.cancel","description":"For passengers: free until the policy's free-cancellation time, after that the late-cancellation\nfee applies (see `cancellation` in the booking). With a secret key the email is not needed; the\npassenger's policy still applies.","summary":"Cancel a booking","tags":["Booking"],"parameters":[{"name":"booking","in":"path","required":true,"description":"The booking reference","schema":{"type":"string"}}],"requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PassengerBookingRequest"}}}},"responses":{"200":{"description":"`PublicBookingResource`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/PublicBookingResource"}},"required":["data"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/quotes":{"post":{"operationId":"v1.quotes.store","description":"Prices the trip for every vehicle type: price lines and totals in cents, plus `available` and a\n`reason` (`capacity` or `fully_booked`) when a vehicle cannot take the trip. Quote-only vehicles\nhave `quote_only: true` and no price. The quote is valid until `expires_at`; book with its `id`.","summary":"Get a quote","tags":["Quote"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateQuoteRequest"}}}},"responses":{"201":{"description":"`QuoteResource`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/QuoteResource"}},"required":["data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/route":{"post":{"operationId":"v1.route.store","description":"The driving route between a pickup and a drop-off, with any stops, for showing on a map before\nasking for a date and prices. `polyline` is a Google encoded polyline, or null when the distance\nis only an estimate.","summary":"Preview a route","tags":["Route"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PreviewRouteRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"points":{"type":"array","items":{}},"distance_meters":{"type":"integer"},"duration_seconds":{"type":"integer"},"polyline":{"type":["string","null"]}},"required":["points","distance_meters","duration_seconds","polyline"]}},"required":["data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/widget\/config":{"get":{"operationId":"v1.widget.config","description":"Branding, services, airports, extras, booking rules, policy texts, theme, the embed modes the\noperator's plan allows, Square settings for the payment frame, and whether payments are ready.","summary":"Widget configuration","tags":["WidgetConfig"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"branding":{"type":"object","properties":{"name":{"type":"string"},"logo_url":{"type":"null"},"support_email":{"type":["string","null"]},"support_phone":{"type":["string","null"]}},"required":["name","logo_url","support_email","support_phone"]},"timezone":{"type":"string"},"currency":{"type":"string"},"test_mode":{"type":"boolean"},"services":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"required":["type","name"]}},"airports":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"}},"required":["code","name","lat","lng"]}},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"price_cents":{"type":"integer"},"max_quantity":{"type":"integer"},"is_pass_through":{"type":"boolean"}},"required":["id","name","price_cents","max_quantity","is_pass_through"]}},"rules":{"type":"object","properties":{"booking_lead_time_minutes":{"type":"integer"},"max_days_ahead":{"type":"integer"},"max_stops":{"type":"integer","const":3},"gratuity_options_bps":{"type":"array","prefixItems":[{"type":"integer","const":0},{"type":"integer","const":1500},{"type":"integer","const":2000},{"type":"integer","const":2500}],"minItems":4,"maxItems":4},"default_gratuity_bps":{"type":"integer"},"tax_bps":{"type":"integer"},"free_cancel_hours":{"type":"integer"},"late_cancel_fee_bps":{"type":"integer"},"no_show_fee_bps":{"type":"integer"},"hold_lead_hours":{"type":"integer"},"hold_buffer_bps":{"type":"integer"}},"required":["booking_lead_time_minutes","max_days_ahead","max_stops","gratuity_options_bps","default_gratuity_bps","tax_bps","free_cancel_hours","late_cancel_fee_bps","no_show_fee_bps","hold_lead_hours","hold_buffer_bps"]},"policies":{"type":"object","properties":{"payment":{"type":"string"},"cancellation":{"type":"string"},"no_show":{"type":"string"}},"required":["payment","cancellation","no_show"]},"theme":{"type":"array","items":{}},"embed_modes":{"type":"array","items":{}},"square":{"type":"object","properties":{"application_id":{"type":"string"},"location_id":{"type":["string","null"]},"environment":{"type":"string"}},"required":["application_id","location_id","environment"]},"maps":{"type":"object","description":"Google Places autocomplete; without a key the widget offers a small list of demo places.","properties":{"browser_key":{"type":["string","null"]}},"required":["browser_key"]},"payments_ready":{"type":"boolean"},"show_branding":{"type":"boolean"}},"required":["branding","timezone","currency","test_mode","services","airports","extras","rules","policies","theme","embed_modes","square","maps","payments_ready","show_branding"]}},"required":["data"]}}}}}}}},"components":{"securitySchemes":{"publishableKey":{"type":"apiKey","in":"header","name":"X-Chauffeur-Circle-Key"},"secretKey":{"type":"http","scheme":"bearer"}},"schemas":{"BookingPaymentStatus":{"type":"string","enum":["card_required","card_saved","authorized","hold_failed","paid","partially_refunded","refunded"],"title":"BookingPaymentStatus"},"BookingResource":{"type":"object","properties":{"reference":{"type":"string"},"status":{"$ref":"#\/components\/schemas\/BookingStatus"},"payment_status":{"$ref":"#\/components\/schemas\/BookingPaymentStatus"},"at_risk":{"type":"boolean"},"marketplace_status":{"type":["string","null"],"description":"Set while the ride is shared on Chauffeur Circle Network: the job's status (open, accepted, ...)."},"quote_request":{"type":"boolean"},"actions":{"type":"array","description":"Which actions the dashboard can offer right now.","items":{}},"service_type":{"$ref":"#\/components\/schemas\/ServiceType"},"pickup_at":{"type":"string"},"estimated_end_at":{"type":["string","null"]},"pickup":{"type":"array","items":{}},"dropoff":{"type":["array","null"],"items":{}},"stops":{"type":"array","items":{}},"hours":{"type":["string","null"]},"passengers":{"type":"integer"},"luggage":{"type":"integer"},"vehicle":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"customer":{"type":"object","properties":{"id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":["string","null"]}},"required":["id","first_name","last_name","email","phone"]},"passenger":{"type":["array","null"],"items":{}},"flight_number":{"type":["string","null"]},"airline":{"type":["string","null"]},"notes":{"type":["string","null"]},"extras":{"type":"array","items":{}},"price":{"type":["array","null"],"items":{}},"estimated":{"type":"object","properties":{"subtotal_cents":{"type":"integer"},"gratuity_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"}},"required":["subtotal_cents","gratuity_cents","tax_cents","total_cents"]},"final":{"type":["object","null"],"properties":{"subtotal_cents":{"type":["integer","null"]},"gratuity_cents":{"type":["integer","null"]},"tax_cents":{"type":["integer","null"]},"total_cents":{"type":["integer","null"]}},"required":["subtotal_cents","gratuity_cents","tax_cents","total_cents"]},"final_adjustments":{"type":["array","null"],"items":{}},"currency":{"type":"string"},"card":{"type":["object","null"],"properties":{"brand":{"type":["string","null"]},"last4":{"type":["string","null"]},"exp_month":{"type":["integer","null"]},"exp_year":{"type":["integer","null"]}},"required":["brand","last4","exp_month","exp_year"]},"source":{"$ref":"#\/components\/schemas\/BookingSource"},"source_domain":{"type":["string","null"]},"utm":{"type":["array","null"],"items":{}},"accepted_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"cancelled_at":{"type":["string","null"]},"cancelled_by":{"type":["string","null"]},"cancel_reason":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["reference","status","payment_status","at_risk","marketplace_status","quote_request","actions","service_type","pickup_at","estimated_end_at","pickup","dropoff","stops","hours","passengers","luggage","vehicle","customer","passenger","flight_number","airline","notes","extras","price","estimated","final","final_adjustments","currency","card","source","source_domain","utm","accepted_at","completed_at","cancelled_at","cancelled_by","cancel_reason","created_at"],"title":"BookingResource"},"BookingSource":{"type":"string","enum":["widget","custom_form","sdk","dashboard"],"title":"BookingSource"},"BookingStatus":{"type":"string","enum":["pending_card","new","accepted","declined","completed","cancelled","no_show"],"title":"BookingStatus"},"CreateBookingRequest":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","description":"The `id` of a quote from POST \/v1\/quotes. The price is recalculated from it on the server."},"vehicle_type_id":{"type":"integer"},"customer":{"type":"object","properties":{"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":"string","maxLength":32}},"required":["first_name","last_name","email","phone"]},"passenger":{"type":"object","description":"Only when someone else travels.","properties":{"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"phone":{"type":["string","null"],"maxLength":32},"email":{"type":["string","null"],"format":"email","maxLength":255}}},"gratuity_bps":{"type":["integer","null"]},"extras":{"type":"array","description":"Replaces the extras chosen on the quote.","items":{"type":"object","properties":{"id":{"type":"integer"},"quantity":{"type":"integer","minimum":1,"maximum":20}},"required":["id","quantity"]},"maxItems":20},"notes":{"type":["string","null"],"maxLength":1000},"flight_number":{"type":["string","null"],"maxLength":16},"airline":{"type":["string","null"],"maxLength":64},"terms_accepted":{"enum":["yes","on","1",1,"true",true]},"source":{"type":["string","null"],"enum":["widget","custom_form","sdk",null]},"utm":{"type":"object","properties":{"source":{"type":["string","null"],"maxLength":100},"medium":{"type":["string","null"],"maxLength":100},"campaign":{"type":["string","null"],"maxLength":100},"term":{"type":["string","null"],"maxLength":100},"content":{"type":["string","null"],"maxLength":100},"referrer":{"type":["string","null"],"maxLength":500}}}},"required":["quote_id","vehicle_type_id","customer"],"title":"CreateBookingRequest"},"CreateQuoteRequest":{"type":"object","properties":{"service_type":{"$ref":"#\/components\/schemas\/ServiceType"},"pickup":{"type":"object","description":"A location is an airport code, or an address with coordinates.","properties":{"airport":{"type":["string","null"],"maxLength":16},"address":{"type":["string","null"],"maxLength":500},"lat":{"type":["number","null"],"minimum":-90,"maximum":90},"lng":{"type":["number","null"],"minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}}},"dropoff":{"type":"object","properties":{"airport":{"type":["string","null"],"maxLength":16},"address":{"type":["string","null"],"maxLength":500},"lat":{"type":["number","null"],"minimum":-90,"maximum":90},"lng":{"type":["number","null"],"minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}}},"stops":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","maxLength":500},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}},"required":["address","lat","lng"]},"maxItems":3},"pickup_at":{"type":"string","description":"ISO-8601. Without an offset it is read in the operator's timezone.","maxLength":40},"hours":{"type":["number","null"],"minimum":0.5,"maximum":24},"passengers":{"type":"integer","minimum":1,"maximum":100},"luggage":{"type":["integer","null"],"minimum":0,"maximum":100},"gratuity_bps":{"type":["integer","null"]},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"quantity":{"type":"integer","minimum":1,"maximum":20}},"required":["id","quantity"]},"maxItems":20}},"required":["service_type","pickup","pickup_at","passengers"],"title":"CreateQuoteRequest"},"PassengerBookingRequest":{"type":"object","description":"Passengers prove access to a booking with its reference (in the URL) and the booker's email.","properties":{"email":{"type":["string","null"],"format":"email","description":"Secret keys (the operator's own server) do not need the passenger's email.","maxLength":255},"reason":{"type":["string","null"],"maxLength":500}},"title":"PassengerBookingRequest"},"PreviewRouteRequest":{"type":"object","properties":{"pickup":{"type":"object","description":"A location is an airport code, or an address with coordinates.","properties":{"airport":{"type":["string","null"],"maxLength":16},"address":{"type":["string","null"],"maxLength":500},"lat":{"type":["number","null"],"minimum":-90,"maximum":90},"lng":{"type":["number","null"],"minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}}},"dropoff":{"type":"object","properties":{"airport":{"type":["string","null"],"maxLength":16},"address":{"type":["string","null"],"maxLength":500},"lat":{"type":["number","null"],"minimum":-90,"maximum":90},"lng":{"type":["number","null"],"minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}}},"stops":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","maxLength":500},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"place_id":{"type":["string","null"],"maxLength":255}},"required":["address","lat","lng"]},"maxItems":3}},"required":["pickup","dropoff"],"title":"PreviewRouteRequest"},"PublicBookingResource":{"type":"object","properties":{"reference":{"type":"string"},"status":{"$ref":"#\/components\/schemas\/BookingStatus"},"payment_status":{"$ref":"#\/components\/schemas\/BookingPaymentStatus"},"quote_request":{"type":"boolean"},"service_type":{"$ref":"#\/components\/schemas\/ServiceType"},"pickup_at":{"type":"string"},"estimated_end_at":{"type":["string","null"]},"pickup":{"type":"array","items":{}},"dropoff":{"type":["array","null"],"items":{}},"stops":{"type":"array","items":{}},"hours":{"type":["string","null"]},"passengers":{"type":"integer"},"luggage":{"type":"integer"},"vehicle":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"flight_number":{"type":["string","null"]},"airline":{"type":["string","null"]},"extras":{"type":"array","items":{}},"price":{"type":["array","null"],"items":{}},"estimated_total_cents":{"type":"integer"},"final_total_cents":{"type":["integer","null"]},"currency":{"type":"string"},"card":{"type":["object","null"],"properties":{"brand":{"type":["string","null"]},"last4":{"type":["string","null"]}},"required":["brand","last4"]},"cancellation":{"type":"object","properties":{"allowed":{"anyOf":[{"type":"string"},{}]}},"required":["allowed"],"additionalProperties":{}},"policies":{"type":"string"}},"required":["reference","status","payment_status","quote_request","service_type","pickup_at","estimated_end_at","pickup","dropoff","stops","hours","passengers","luggage","vehicle","flight_number","airline","extras","price","estimated_total_cents","final_total_cents","currency","card","cancellation","policies"],"title":"PublicBookingResource"},"QuoteResource":{"type":"object","properties":{"id":{"type":"string"},"expires_at":{"type":"string"},"service_type":{"$ref":"#\/components\/schemas\/ServiceType"},"pickup_at":{"type":"string"},"estimated_end_at":{"type":["string","null"]},"pickup":{"type":"array","items":{}},"dropoff":{"type":["array","null"],"items":{}},"stops":{"type":"array","items":{}},"hours":{"type":["string","null"]},"passengers":{"type":"integer"},"luggage":{"type":"integer"},"distance_meters":{"type":["integer","null"]},"duration_seconds":{"type":["integer","null"]},"airport":{"type":["string","null"]},"vehicles":{"type":"array","items":{"type":"object","properties":{"vehicle_type_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"image_url":{"type":["string","null"]},"max_passengers":{"type":"integer"},"max_luggage":{"type":"integer"},"available":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["capacity","fully_booked",null]},"quote_only":{"type":"boolean"},"price":{"type":["object","null"],"properties":{"lines":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amount_cents":{"type":"integer"},"pass_through":{"type":"boolean"}},"required":["type","label","amount_cents","pass_through"]}},"subtotal_cents":{"type":"integer"},"gratuity_bps":{"type":"integer"},"gratuity_cents":{"type":"integer"},"tax_bps":{"type":"integer"},"tax_cents":{"type":"integer"},"pass_through_cents":{"type":"integer"},"total_cents":{"type":"integer"},"currency":{"type":"string"}},"required":["lines","subtotal_cents","gratuity_bps","gratuity_cents","tax_bps","tax_cents","pass_through_cents","total_cents","currency"]}},"required":["vehicle_type_id","name","description","image_url","max_passengers","max_luggage","available","reason","quote_only","price"]}}},"required":["id","expires_at","service_type","pickup_at","estimated_end_at","pickup","dropoff","stops","hours","passengers","luggage","distance_meters","duration_seconds","airport","vehicles"],"title":"QuoteResource"},"ServiceType":{"type":"string","enum":["point_to_point","airport","hourly"],"title":"ServiceType"}},"responses":{"ValidationException":{"description":"Validation error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Errors overview."},"errors":{"type":"object","description":"A detailed description of each field that failed validation.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message","errors"]}}}},"ModelNotFoundException":{"description":"Not found","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}}}}}