Widget API overview

With the Widget API you build your own booking experience: a fully custom booking flow on your site, or a native app. It is for when the booking widget cannot be shaped into what you need. It is the API that Cliento's own widget runs on.

It is a JSON API called straight from the customer's browser. It needs no API key, and one account id is all you need to start.

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 identifies your Cliento account, which is one location of a business. It is the same id the booking widget uses. You will find it in Cliento (go to Admin > Onlinebokning > Bokningssida / Widget).

For example, to fetch the services and resources of the account 1uAKYvE7mWcnxxdMuixis:

curl https://apibk.cliento.com/api/v2/partner/cliento/1uAKYvE7mWcnxxdMuixis/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 and CORS is open for any origin, so you need no server of your own.

Send these headers on every request:

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 expect to update a custom client when the API changes. Accept responses with fields you do not know, and ignore them.

Rate limits

The API is rate limited. 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

Some accounts require a Google reCAPTCHA v3 token on the booking requests. They have web_requiresCaptcha set to true in their settings. The token goes in the captchaResponse field of /booking/reserve, /booking/customer, /booking/confirm and /booking/pay. For an account 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, tell us in the chat at the bottom of the page which 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 action reserve for /booking/reserve, 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.

Endpoints

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 {ref} in the path identifies the booking by itself. See Retrieving and cancelling a booking.