Skip to content

Setmore API (v2)

Getting Started

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.

Request access

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

What you can build

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.

Can I sell my integration?

Currently, no. We do not have a marketplace to sell or share integrations at this time.

Need help?

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.

Response envelope

All responses share one envelope:

  • Success (single resource): { "data": { ... } }
  • Success (list): { "data": [ ... ], "cursor": "..." }. cursor is 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." }
      ]
    }

Error codes

CodeMessage
server_errorGeneric server error.
client_errorGeneric client error.
resource_not_foundThe requested resource does not exist.
token_expiredThe bearer token has expired.
missing_authorizationNo Authorization: Bearer credentials were found on the request.
unsupportedThe operation is not supported.
parameter_not_foundA required parameter was not supplied.
parameter_invalidA parameter's value is invalid.
action_forbiddenThe action is not authorized for this merchant.
out_of_rangeA 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_conflictThe request conflicts with the current state of the resource.
payload_too_largeA value exceeded the allowed size limit.

Time standards

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:00Z and 2026-11-19T08:30:00+08:00 are the same moment. Read the offset in a value rather than assuming it is UTC.

  • Requests accept Z or any numeric offset.

  • Responses differ by endpoint, so check the field:

    WhereOffset returnedExample
    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:00Z
    Available slots (GET /slots)The offset of the requested timezone: +08:00 for Asia/Singapore, and Z or another offset for other zones. It changes with daylight saving time.2026-11-19T08:30:00+08:00
    Class sessions (GET /slots/class/{class-key})UTC, Z. The requested timezone only decides which day a session is listed under.2026-01-20T09:00:00Z

Rate limiting

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.

Authentication

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.

1. Exchange your refresh token

Send a GET request to exchange your refresh token for an access token:

GET https://developer.setmore.com/api/v2/o/oauth2/token?refreshToken={your_refresh_token}

2. Read the token response

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"
    }
  }
}
FieldDescription
access_tokenThe bearer token to send with your API requests.
token_typeAlways BEARER.
expires_inHow long the access token is valid, in seconds.
user_idThe id of the account the token belongs to.

3. Send the access token with your requests

Add the access token to the Authorization header of every request:

Authorization: Bearer {access_token}

Token lifespan

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.

Languages
Servers
Production server
https://developer.setmore.com/api/v2