Cliento API reference: Booking

Base URL: https://api.cliento.com

The Booking APIs let an integration read a location's bookings. They also list its resources and its services. Creating and changing bookings through the API is coming soon.

A booking is built from these:

• Resources. A resource is what gets booked. It is most often a person, sometimes a room or a piece of equipment.
• Services. A service is something the location offers, such as a haircut. It has a name and a default duration and price.
• Resource services. A resource service is a service as one resource offers it. It uses the service's duration and price unless the resource has its own.
• Schedules. A schedule says when a resource works.
• Availability. Availability says when a service can be booked. It is worked out from the resource services, the schedules and the bookings already made.
• Bookings. A booking is a time on a resource, usually for a customer and one or more services.

Getting started with bookings

A booking needs other things to exist first. Set them up in this order:

1. Add a resource. A booking is always made on a resource, so the location needs at least one. Resources are added in Cliento today. List them with GET /v1/locations/{locationId}/resources.
2. Add the services the location offers. Services are added in Cliento today. List them with GET /v1/locations/{locationId}/services.
3. Enable each service for the resources that offer it. That creates a resource service, with the duration and price that apply to that resource. It is done in Cliento today. Read a resource's resource services with GET /v1/locations/{locationId}/resources/{resourceId}/services.
4. Create the customer the booking is for. Create a person with POST /v1/locations/{locationId}/persons, a company with POST /v1/locations/{locationId}/companies, or a vehicle with POST /v1/locations/{locationId}/vehicles.
5. Create the booking. A booking is a time on the resource, for the customer, with one or more of the resource's services. Bookings are made in Cliento or by customers online today. Read them with GET /v1/locations/{locationId}/bookings.

Adding resources and services, enabling a service for a resource and creating a booking through the API are coming soon.

A reservation skips steps 2 to 4. It only blocks time on a resource, such as a lunch break or a staff meeting, and needs no service and no customer.

Only the resource is required. Staff can make a booking in Cliento without a customer, without a service, or with a service the resource is not enabled for. Expect to read bookings like that. A schedule is not required either: it decides when a service can be booked online, not whether a booking can exist.

Resources

The Resources API lists a location's resources and the services each one can be booked for. Use it to show which resources can be booked. A resource's resource services give the duration and price of each service.

A resource is what gets booked in the calendar. It is most often a person, sometimes a room or a piece of equipment. Every booking is made on at least one resource.

A resource belongs to one location and has an id of the form res_.... GET /v1/locations/{locationId}/resources lists the resources. Reading resources needs the scope resources:read, and reading a resource's services needs services:read.

• A resource is not a staff member. A staff member is a person who works at the location. A resource is what bookings are made on. A staff member names the resources it is linked to in resourceIds.
• Resources are listed in groups. groupId names the group. GET /v1/locations/{locationId}/resource-groups lists the groups in the order the location shows them.
• The services a resource can be booked for are its resource services, read with GET /v1/locations/{locationId}/resources/{resourceId}/services. Each is one service as this resource offers it. It has the service's name, description, group, type and VAT. Its duration and price are the resource's own where the resource has them, and the service's defaults where it does not.
• The same services with the location's defaults are read with GET /v1/locations/{locationId}/services?resourceId=....
• onlineBookingEnabled says whether the resource is open for online booking at all. Whether a given service can be booked online with it is onlineBookingAllowed on the resource service.
• status is paused for a resource that is paused for billing, up to and including pausedUntil. A paused resource keeps its bookings but takes no new online bookings.
• A deleted resource is left out of the list. It still answers by id, with status deleted, because earlier bookings refer to it.
• onlineName is the name customers see in online booking, when it differs from name.

List resources

GET /v1/locations/{locationId}/resources

Scope: resources:read

Stability: preview

The location's resources, without those that are deleted.

Parameters

Responses

Get a resource

GET /v1/locations/{locationId}/resources/{resourceId}

Scope: resources:read

Stability: preview

Also answers for a deleted resource, with status deleted.

Parameters

Responses

Get a resource by id

GET /v1/resources/{resourceId}

Scope: resources:read

Stability: preview

The same resource as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries locationId.

Parameters

Responses

List a resource's resource services

GET /v1/locations/{locationId}/resources/{resourceId}/services

Scope: services:read

Stability: preview

Lists the services the resource can be booked for, in the order the location lists its services. Each is a resource service. It has the duration, price and online booking setting that apply for this resource. ownValues says whether they are the resource's own or the service's defaults.

Parameters

Responses

Get a resource service

GET /v1/locations/{locationId}/resources/{resourceId}/services/{serviceId}

Scope: services:read

Stability: preview

One service as this resource offers it.

Parameters

Responses

List resource groups

GET /v1/locations/{locationId}/resource-groups

Scope: resources:read

Stability: preview

The groups the location's resources are listed under, in display order.

Parameters

Responses

Services

The Services API lists the services a location offers, with their names, durations and prices. Use it to show what can be booked at a location.

A service is something a location offers, such as a haircut, a massage or a class. The location gives it a name and a default duration and price.

A resource service is a service as one resource offers it. It uses the service's defaults unless the resource has its own duration or price. To read what one resource offers, read that resource's resource services.

A service belongs to one location and has an id of the form svc_.... GET /v1/locations/{locationId}/services lists the services in the order the location shows them. Reading needs the scope services:read.

• Services are listed in groups. groupId names the group. GET /v1/locations/{locationId}/service-groups lists the groups in display order.
• A resource service says that a resource can be booked for a service. It has the service's name, description, group, type and VAT. Its duration, price and online booking setting are the ones that apply to that resource. Use them when you know which resource a booking is for.
• ownValues says where a resource service's values come from. When it is false, the resource service follows the service's defaults and changes when they do. When it is true, it has its own values, which stay when the service changes.
• Resource services are read in two places: in resourceServices on the service, one for each resource it can be booked for, and per resource under /v1/locations/{locationId}/resources/{resourceId}/services.
• A service can be booked online with a resource when three things hold: the service is shown online (shownOnline), the resource service allows online booking (onlineBookingAllowed), and the resource is open for online booking (onlineBookingEnabled on the resource). A resource that is paused takes no online bookings whatever the three say.
• onlineBookingAllowed on the service is the default. The resource service follows it unless the resource has its own setting. A service can be shown without being bookable, so that customers see it and call.
• afterTimeMinutes is time kept free after the booking. It is not part of what the customer is told the service takes.
• priceFrom marks a starting price: the final price is set at the visit.
• An add-on (addOn) is booked together with another service, never on its own.
• A service can have parts with different VAT rates, listed in vatParts. A vaccination is an example: the vaccine is a medical part with no VAT, and the certificate issued with it is a part at 25 % VAT. The service's price is then the sum of the parts' prices. When the service is paid for at the point of sale or online, each part is sold at its own rate. The service's vatPercent is the single rate used where the service is not split into its parts.
• A deleted service is left out of the list. It still answers by id, with status deleted, because earlier bookings refer to it.
• A location can charge more in the evening or on holidays. Those prices are not returned yet; price is the ordinary one.
• Prices follow "Amounts" in the introduction.

List services

GET /v1/locations/{locationId}/services

Scope: services:read

Stability: preview

The location's services in the order the location lists them, without those that are deleted.

Parameters

Responses

Get a service

GET /v1/locations/{locationId}/services/{serviceId}

Scope: services:read

Stability: preview

Also answers for a deleted service, with status deleted.

Parameters

Responses

Get a service by id

GET /v1/services/{serviceId}

Scope: services:read

Stability: preview

The same service as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries locationId.

Parameters

Responses

List service groups

GET /v1/locations/{locationId}/service-groups

Scope: services:read

Stability: preview

The groups the location's services are listed under, in display order.

Parameters

Responses

Schedules

Coming soon. Read and change when a location is open and when each resource works.

Availability

Coming soon. Ask when a service can be booked, across the resources that offer it.

Bookings

The Bookings API lets an integration read a location's bookings: the ones that start in a period, or one by id. Use it when another system needs to show or count what is booked, such as a customer portal, a reporting tool or a screen in the salon. Creating, moving and cancelling bookings through the API is coming soon.

A booking is a time on one or more resources. Its type says what kind it is:

• An appointment has the services that were booked and the customers it is for.
• A class has services and customers too. It has a number of places, and each customer books one.
• A reservation only blocks the time, such as a lunch break or a staff meeting. It has no service and no customer.

A booking belongs to one location and has an id of the form bkg_.... Reading needs the scope bookings:read.

• The list takes a period: from and to, at most 62 days apart, matched against startsAt. Add resourceId for one resource's bookings, or customerId for one person's, company's or vehicle's.
• resources names the resources the booking is on. Exactly one is the primary resource, the one the booking was made with.
• customers names the persons, companies and vehicles the booking is for. The id's prefix says which type, and that type's API has the full record.
• A customer on a booking has its name, when the customer has one. A key that also has the scope customers:read gets the contact details too: the phone numbers, the email address, the number that identifies the customer and what the customer wrote when booking (customerNote). That number is identityNumber for a person, organisationNumber for a company and registrationNumber for a vehicle.
• A customer registered at a location your key cannot use is returned with its name only.
• The customer's values are the current ones, read with the booking. Read and change the customer itself through its own API.
• The services are kept as they were when the booking was made: name, durationMinutes and price. A later change to the service, or to the resource service, does not change a booking already made. serviceId still refers to the service.
• startsAt and endsAt are in UTC. They are the start and end of the time taken on the resource. The last afterTimeMinutes of that time are kept free after the services, so the services end that many minutes before endsAt.
• status is booked until staff set show, no_show or done, or the booking is cancelled. A cancelled booking stays readable and stays in the list.
• Each customer has a status of their own. On an appointment it is the booking's. On a class, one customer can cancel while the others stay booked. places and placesBooked say how many places the class has and how many are taken.
• A nextCursor here marks a start time, not a booking. It stays good when the last booking of a page is moved or removed before you ask for the next page.
• A booking that is moved while you page can show up twice if it moves to a later time, and can be missed if it moves to an earlier one. Read the period again when that matters.
• A booking also has its payments, the sales it was sold in, its SMS reminders, the location's own customFields, and the series it recurs in.
• A sale is identified by saleId. It is read in full from the Sales API, which is coming soon. Reviews are read from the Reviews API, which is coming soon too.
• A reservation says what the time is blocked for in reservationType, such as lunch or vacation, when staff gave a reason.
• Nothing from a patient's medical record is returned. A location that keeps medical records has its health declarations and warnings in the record, not in the booking.
• A booking that a customer has started online and not yet completed is not returned, in the list or by id.
• Prices follow "Amounts" in the introduction.

List bookings

GET /v1/locations/{locationId}/bookings

Scope: bookings:read

Stability: preview

The location's bookings that start in a period, in order of start time, one page at a time. The period is at most 62 days; read a longer one in several calls. Cancelled bookings are included, with status cancelled. A booking a customer has started online and not yet completed is not.

Parameters

Responses

Get a booking

GET /v1/locations/{locationId}/bookings/{bookingId}

Scope: bookings:read

Stability: preview

Parameters

Responses

Get a booking by id

GET /v1/bookings/{bookingId}

Scope: bookings:read

Stability: preview

The same booking as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries locationId.

Parameters

Responses

Schemas

Booking

A time on one or more resources, at one location. An appointment or a class has the services that were booked and the customers it is for. A reservation only blocks the time. The services' names, durations and prices are kept as they were when the booking was made, so a later change to a service does not change the booking.

BookingCustomer

A customer on a booking: a person, a company or a vehicle, with that customer's own status on the booking. It has the customer's name, when there is one. An API key that also has the scope customers:read gets the contact details and the number that identifies the customer too, so a booking can be shown without reading each customer. These are the customer's current values. The customer is changed through its own API.

BookingList

BookingPayment

A payment for a booking: made online when booking, in advance, or at the point of sale. Belongs to the booking, and to one of its customers when it was made for one.

BookingReminder

An SMS reminder sent, or to be sent, to a customer about a booking.

BookingResource

A resource a booking is on.

BookingSale

A sale that a booking was sold in: a sale at the point of sale, an order or an invoice. The sale belongs to a merchant and is read in full from the Sales API, which is coming soon; this is the part a booking refers to.

BookingSeries

A series of bookings that recur. Each booking in it is a booking of its own and has the series' id. The series has the rule the bookings were made from.

BookingService

A service on a booking, with its name, duration and price as they were when it was booked.

CustomField

A field a location has added of its own, with the value given for one booking or one customer on it.

Error

The body of every non-2xx response.

IdentityNumber

A number issued by an authority that identifies a person, such as a personnummer. The accepted format of each type is listed under Persons.

Resource

What gets booked: most often a person, sometimes a room or a piece of equipment. A resource belongs to one location.

ResourceGroup

A group of resources: a heading the location lists them under, such as "Stylists" or "Rooms".

ResourceGroupList

ResourceList

ResourceService

A service as one resource offers it: what is booked. It is identified by its resource and its service. The name, description, group, type and VAT are the service's, and are changed on the service. The duration, after-time, price and online booking setting are the service's defaults, unless the resource overrides them with its own, as ownValues says.

ResourceServiceList

Service

A service as the location defines it: something the location offers, with its name and the default duration, price and settings. Belongs to a location. What is booked is a resource service, which follows these defaults unless the resource overrides them.

ServiceGroup

A group of services: a heading the location lists them under, such as "Hair" or "Colour".

ServiceGroupList

ServiceList

ServiceVatPart

One part of a service that consists of several, with its share of the price and the VAT rate that part is booked at.