Setmore API (v2)
Setmore is an appointment scheduling platform that lets you book customer appointments, choose from available services, and manage appointments across multiple staff calendars under one account. This API provides the Setmore functions you need to build tools and integrations, from creating bookings and fetching available slots to managing services, categories, working hours, and staff and customer contacts.
To request access to the API, first make sure you've already signed up for a Setmore Pro account. Then send an email to api@setmore.com and include the following information:
- Your Name
- Email address that's registered to your Setmore account
- A brief description of what you'd like to use the API for
The Setmore API enables you to build custom booking flows, retrieve calendar schedules, and manage customer and staff contacts. With this API, your integration can:
- Manage Bookings: Create, update, fetch, and delete appointments, group class sessions, and events, and add or remove customers on a class session.
- Retrieve Availability: Query bookable time slots for a staff member and service, check seat availability for upcoming class sessions, and read staff working hours.
- Synchronize Services & Categories: Create, update, and list services and categories, and assign staff members to services.
- Manage Contacts: Read staff contacts, and create, update, delete, and bulk-import customer contacts.
Developer & Setmore API Support: Send an email to api@setmore.com.
General Inquiries: Reach out to us at help@setmore.com.
Upgrading from v1? See the Changelog for what changed in v2 and how to migrate.
All responses share one envelope:
- Success (single resource):
{ "data": { ... } } - Success (list):
{ "data": [ ... ], "cursor": "..." }.cursoris omitted when there is no next page. - Error (any non-2xx):
{ "errors": [ { "code": "...", "message": "..." } ] }. This is always an array, even for a single error, e.g.:{ "errors": [ { "code": "resource_not_found", "message": "The requested resource does not exist." } ] }
| Code | Message |
|---|---|
server_error | Generic server error. |
client_error | Generic client error. |
resource_not_found | The requested resource does not exist. |
token_expired | The bearer token has expired. |
missing_authorization | No Authorization: Bearer credentials were found on the request. |
unsupported | The operation is not supported. |
parameter_not_found | A required parameter was not supplied. |
parameter_invalid | A parameter's value is invalid. |
action_forbidden | The action is not authorized for this merchant. |
out_of_range | A range or count is outside what is allowed (e.g. a slots date range over 7 days, or a booking's consumer_ids count). |
resource_conflict | The request conflicts with the current state of the resource. |
payload_too_large | A value exceeded the allowed size limit. |
Every date and time sent to or returned by the API is an RFC 3339 date-time: YYYY-MM-DDThh:mm:ss followed by an offset, which is either Z (UTC) or a numeric offset such as +08:00 or -05:00.
The offset is required. A time without one is rejected, and fractions of a second are not supported, so send whole seconds.
An offset is not a time zone.
2026-11-19T00:30:00Zand2026-11-19T08:30:00+08:00are the same moment. Read the offset in a value rather than assuming it is UTC.Requests accept
Zor any numeric offset.Responses differ by endpoint, so check the field:
Where Offset returned Example Bookings and events ( start_at,end_at,created_at)UTC, Z. A time sent with an offset comes back as the same moment in UTC.2026-11-19T00:30:00ZAvailable slots ( GET /slots)The offset of the requested timezone:+08:00forAsia/Singapore, andZor another offset for other zones. It changes with daylight saving time.2026-11-19T08:30:00+08:00Class sessions ( GET /slots/class/{class-key})UTC, Z. The requestedtimezoneonly decides which day a session is listed under.2026-01-20T09:00:00Z
To ensure high availability and consistent performance, the Setmore API is subject to rate limiting. Usage is monitored continuously. While standard traffic limits apply, Setmore reserves the right to dynamically adjust or restrict request thresholds per minute based on system health and client consumption patterns. If your application exceeds these thresholds, the API returns an HTTP 429 Too Many Requests response.
Every request must be authenticated with an access token, sent as a bearer token. When your access request is approved, the Setmore team provisions a permanent refresh token and sends it to you by email. Use the refresh token to generate access tokens with the token endpoint below.
Keep your refresh token secret. Store it securely on your server and never expose it in client side code.
A successful exchange returns the access token and its details:
{
"response": true,
"data": {
"token": {
"access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"token_type": "BEARER",
"expires_in": 604799,
"user_id": "XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX"
}
}
}| Field | Description |
|---|---|
access_token | The bearer token to send with your API requests. |
token_type | Always BEARER. |
expires_in | How long the access token is valid, in seconds. |
user_id | The id of the account the token belongs to. |
Access tokens are short lived and expire after the number of seconds given in expires_in. Track the expiry time in your integration and call the token endpoint again to get a new access token before the current one expires. A request made with an expired token fails with the token_expired error code.