Clientlyopenapi.json
Open API

Let an agent book the appointment.

Everything a client can do on the booking page, an agent can do over HTTP: read services, find free times, book and cancel. Same rules, same database — no shortcuts.

No API key

Reading a business, its services and its availability needs nothing — it is already public on the booking page. Booking needs no key either, but hands back a `manage_token`. That token is the only way back to the booking, so keep it.

Nothing is relaxed for an agent

Every booking goes through the same function the booking page uses. Opening hours, absence, minimum notice and the booking window are all checked again inside the transaction that writes. A slot that was free a moment ago may still be refused with `slot_taken` — that is the system working.

Endpoints

GET/businesses/{slug}The business and its booking rules
GET/businesses/{slug}/servicesWhat can be booked
GET/businesses/{slug}/staffWho works there, and what they do
GET/businesses/{slug}/availabilityFree slots for a service
POST/businesses/{slug}/bookingsMake a booking
GET/bookings/{manage_token}Read a booking
POST/bookings/{manage_token}/cancelCancel a booking

Conventions

  • Times are ISO 8601 with an offset.
  • Money is an integer of minor units plus a currency code. 45000 NOK means 450 kroner.
  • Durations are whole minutes.
  • Errors are always { error: { code, message } } with a documented code.

An example

Find a free time and book it. Swap the slug for the business's own.

# 1. What does this shop do?
curl https://www.clientlyapp.com/api/v1/businesses/studionord/services

# 2. When is it free?
curl "https://www.clientlyapp.com/api/v1/businesses/studionord/availability\
?service_id=SERVICE_ID&days=7"

# 3. Book the first free slot. Omit staff_id to let the shop
#    assign whoever has the fewest bookings that day.
curl -X POST https://www.clientlyapp.com/api/v1/businesses/studionord/bookings \
  -H "Content-Type: application/json" \
  -d '{
        "service_id": "SERVICE_ID",
        "starts_at": "2026-11-25T13:00:00.000Z",
        "name": "Ola Nordmann",
        "email": "ola@example.no"
      }'

# Keep the manage_token from the response: it is the only
# way back to the booking.
curl https://www.clientlyapp.com/api/v1/bookings/MANAGE_TOKEN

Error codes

validation_failed400The request body or query was not valid.
not_found404No such business, service or booking.
bookings_closed409This business is not taking online bookings.
slot_taken409That time is no longer free.
outside_booking_window409That time is further ahead than this business accepts.
below_minimum_notice409That time is sooner than this business accepts.
staff_unavailable409That person is not available then.
service_not_offered_by_staff409That person does not perform this service.
past_cutoff409This booking can no longer be cancelled online. Contact the business.
booking_state_final409This booking has already been cancelled, completed or marked as a no-show.
rate_limited429Too many requests. Slow down and try again.
internal_error500Something went wrong on our side.

Limits

Per IP address: reads are generous, bookings are 5 an hour per business. A refusal is 429 with a Retry-After header.

The full description

OpenAPI 3.1, generated from the same error table the endpoints answer with — so the documentation cannot drift away from the behaviour.

Open openapi.json