REST API overview
The Cliento REST API is the same API that powers the booking widget. You can use it to build your own booking experience, for example a fully custom widget or a native app. This section documents everything you need to search availability and create bookings.
If you are new to the API, start with the Booking flow guide.
Base URL
All endpoints in this documentation are relative to the following base URL:
https://apibk.cliento.com/api/v2/partner/cliento/{id}
The id is the unique key for your Cliento account, the same key used by the
booking widget. You will find it in Cliento (go to Admin > Onlinebokning > Bokningssida / Widget).
Example: fetch services and resources for the account 7DUdvNGJ5LXQK83UlWTJ1O:
curl https://apibk.cliento.com/api/v2/partner/cliento/7DUdvNGJ5LXQK83UlWTJ1O/ref-data/
Authentication
The API does not use API keys. Requests are unauthenticated and the account is
identified by the id in the URL. Calls are made directly from the customer's
browser, CORS is open for any origin, so no server of your own is needed.
Send these headers on every request:
| Header | Value |
|---|---|
Accept | application/json |
Content-Type | application/json (for POST requests) |
API stability
The API is not versioned. It is the API behind Cliento's own widget and it changes when the widget does. Changes are made with care, but a custom client must be prepared to be updated when the API changes. Read unknown fields leniently and ignore fields you do not use.
Rate limits
The API is rate limited in two ways: per source IP on the calls that reserve
and confirm bookings, and per reservation (cbUuid) on the calls that add
customer details, fetch confirmation options and confirm or pay. Normal
customer behaviour stays well within the limits. A limited request returns
429 with a Retry-After header and a body like
{"key": "retry", "retryAfterSeconds": 30}. Wait that long and repeat the
same call. Do not poll the status endpoint
more often than every few seconds.
Captcha
Accounts with web_requiresCaptcha set to true in their
settings require a Google reCAPTCHA v3
token on the booking requests. The token goes in the captchaResponse field
of /booking/reserve, /booking/customer, /booking/confirm and
/booking/pay. Accounts without the setting send null.
The captcha uses Cliento's reCAPTCHA site key, and reCAPTCHA only issues tokens on domains registered for that key. Before your client goes live on an account with captcha, contact support@cliento.com with the domains your booking UI runs on. Cliento registers them and gives you the site key. Then:
// Load https://www.google.com/recaptcha/api.js?render={siteKey}
const token = await grecaptcha.execute(siteKey, { action: 'confirm' });
// send as captchaResponse
Fetch a fresh token for every request, tokens are single use and short lived.
The widget uses the actions customer for /booking/customer and confirm
for /booking/confirm and /booking/pay. A rejected token returns 400 with
code 0 and the message Captcha failed.
Errors
Successful responses use 200, 201 or 204. Error responses use standard
HTTP status codes. 400 responses have a JSON body with a numeric code, a
message and details, for example
{"code": 3, "message": "Reservation not found for uuid: …", "details": ""}.
Other error responses have a short plain text body or no body at all.
| Status | Meaning |
|---|---|
| 400 | The request body or parameters are invalid, or the request was rejected by the captcha. The body is JSON with code, message and details |
| 402 | Payment required or a payment result, see Payments |
| 403 | Not allowed: a wrong PIN, an unknown reservation on /booking/pay, or a cancellation past the deadline. Usually an empty body |
| 404 | Unknown account id or entity |
| 409 | Conflict, the operation is not possible in the current state |
| 410 | From /booking/reserve, the slot is no longer available. From /booking/{cbUuid}/status, the reservation is gone. Other calls on an expired reservation return 404 |
| 418 | The request was blocked by the abuse checks. Treat like 403 |
| 429 | Rate limited, see Rate limits |
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /settings/ | Booking settings for the account |
| GET | /ref-data/ | Services, resources and mappings |
| GET | /custom-fields/resource/{resourceHashId} | Custom form fields |
| GET | /resources/slots | Available slots |
| POST | /booking/reserve | Reserve a slot |
| POST | /booking/release | Release a reservation |
| POST | /booking/customer | Add customer details |
| POST | /booking/confirmation-options | Get confirmation options |
| POST | /booking/confirm | Confirm the booking |
| POST | /booking/payment-provider | Choose payment provider |
| POST | /booking/pay | Pay and confirm |
| POST | /booking/{cbUuid}/status | Booking status |
| POST | /klarna/session | Create a Klarna session |
| POST | /booking/validate-voucher | Validate a voucher |
| POST | /booking/voucher | Apply or remove a voucher |
| GET | /reviews/ | Reviews |
The payment endpoints are only used when the account requires online payment, see Payments.
Two more endpoints retrieve and cancel an existing booking. They are not under the account base URL, the booking ref alone identifies the booking. See Retrieving and cancelling a booking.
| Method | Path | Description |
|---|---|---|
| GET | https://apibk.cliento.com/api/v2/booking/{ref} | Retrieve a booking |
| DELETE | https://apibk.cliento.com/api/v2/booking/{ref} | Cancel a booking |