Setmore API Guide: Access, Tokens, Endpoints and Limits

What the Setmore API is, and who it is for

Setmore offers a REST API on its Pro plan for building custom booking tools and integrations ^[1]. The published specification lists ten endpoints covering staff, services, categories, customers, available slots and appointments ^[2]. It is small by design. There are no webhooks and no call to reschedule or cancel a booking, and that shapes everything you can build on it. For an agency that wants a branded booking flow on a client's own website, the scope is enough. A team that needs to react the moment a customer cancels will have to poll the appointments endpoint or bring in Zapier to cover the gap.

The API suits agencies and in-house developers who want a custom booking front end, a branded app or a sync into another system. Setmore names HTML embeds, React integrations and custom front ends as options. A small business owner who just wants two tools to talk will usually be better served by Zapier or a native integration, and our Setmore integrations guide covers those. Code is the last resort here.

Getting access: the plan, the email and the cost

API access requires a Setmore Pro account, and the pricing grid marks it as Pro only ^[3]. There is no self-serve key in the dashboard. You sign up for Pro, then email api@setmore.com with your name, the email registered to your Setmore account and a short description of what you want to build. Approval is manual, so build some lead time into your project plan.

The money side is modest. The API costs nothing beyond Pro, and on annual billing a single Pro user costs $60 a year, by our arithmetic, so a dedicated developer account is cheap. A live account and a separate test account at one user each come to $120 a year on annual billing, again our arithmetic. That is a small fraction of the developer time a custom booking front end usually takes. The real cost is development time, and the missing webhooks add polling work that other APIs avoid. For the full plan breakdown, see our Setmore pricing guide.

Authentication: one permanent token, many short ones

Refresh tokens and access tokens

Once you are approved, Setmore emails a permanent refresh token ^[4]. You exchange it for a short-lived access token whenever you need one. The exchange is a GET request to the OAuth2 token endpoint with the refresh token as a query parameter, and it returns a bearer access token, its type and its lifetime. Every other call carries that bearer token, and the help center describes the scheme as OAuth 2.0. Store the refresh token like a password. Anyone who holds it can mint tokens for your account.

Token lifetime and the single host

The sample response shows an expiry of 604,799 seconds, just under seven days by our arithmetic. Setmore warns that access tokens are transient and that your integration must refresh them before they lapse. Build the refresh into your client, not into a calendar reminder. Because the token lasts about 168 hours, a server job that refreshes it once a day always holds a token with days to spare, which is simpler and safer than refreshing only after a request fails with an authorization error. There is also only one host. The specification lists a single production server at developer.setmore.com under api/v1/bookingapi, with no separate test host. That detail matters more than it looks, as the section on testing explains.

The ten endpoints, call by call

Staff, services and categories

Start with staff. The staff endpoint returns every staff member in the company, with a unique key, first and last name, email, phone numbers, image and notes, and you need that key for slot searches and bookings. The services endpoint lists every service with its key, name, the staff who deliver it, duration and buffer in minutes, cost, currency, description and image, so your front end can show the real length of a booking. Categories come with a key, a name, their order on the page, their services and a deleted flag, and a separate endpoint returns the services within one category. Cache all of it. These lists change rarely.

Customers

Creating a customer is a POST with the customer's details, and it returns the new customer with its key, which you need before you can book. First name is required, and an invalid first name returns its own error. A record holds names, email, phone numbers including work and home lines, address, city, state, postal code, image URL, notes and a set of arbitrary additional fields for data from your own form. The customer search takes a first name, a phone number or an email. Search by email first to avoid duplicates. They can still be merged later, but only in the web app.

Available slots

The slots endpoint is the call that turns Setmore into a booking engine. It takes a staff key, a service key and a date in day, month, year format, plus optional flags to include off-hours slots or allow double booking, and it maps each date to a list of times in hour and minute format. A slot limit caps the response at 30, and wrong date formats or unknown service keys return named validation errors. You can pass an IANA time zone; if you omit it, slots come back in the company's time zone. For an online coach with clients abroad, always pass the customer's zone.

A custom booking page will call this endpoint more than any other, once for each date a customer looks at. With a single date per call, a front end that shows a whole week for one practitioner needs seven calls. Plan for that.

Appointments and labels

The create-appointment call takes staff key, service key, customer key, start time and end time, plus an optional comment and label, and returns the new appointment. Times use a year-month-day format with hours and minutes in Zulu time, for example 2025-01-20T09:00Z, so convert local times to UTC before posting. Mixing formats between the slots and appointment calls is the classic first bug. Another customer can take a slot between the moment it is shown and the moment it is booked, so the safest flow fetches slots again for that date just before posting.

Listing appointments takes a start and an end date. You can add a staff key to narrow the list and request customer details in the same response; without one, the call covers the whole company. Responses carry a cursor for the next page, so loop until no cursor comes back. The only write call on an existing booking updates its label, with the appointment ID in the path. Labels mark status such as Confirmed, Done, No-Show or Paid.

Limits, errors and testing without a sandbox

The API is rate limited and usage is monitored continuously. Setmore reserves the right to adjust thresholds per minute based on system health and client behavior, and an application that exceeds them gets an HTTP 429 response ^[4]. No fixed number is published. Back off and retry. A client that caches staff and service lists, spaces out slot searches and retries after a 429 with a growing delay will stay well clear of trouble. Responses carry a success flag and a message, errors add localized error codes, and the label update has its own permission error. Log the message text; it is more useful than the status code.

There is no sandbox, so every request runs against a live account, and Setmore itself recommends a separate account for testing. A test booking triggers the same customer and staff emails as a real one, and created customers stay in your contacts. A developer who tests with a colleague's real email can end up confusing that colleague with a string of appointments. Open a second Pro account with fake staff, services and customer emails you control, then clean up test records afterward by merging or deleting them in the web app.

What the API cannot do

The specification has no endpoint to reschedule, cancel or delete an appointment, no endpoint to change a customer once created, no payments, no classes and no webhooks ^[2]. Beyond creating bookings and reading data, staff must work in Setmore itself. That is the honest summary.

The missing cancel call is the one users notice. Customers can still reschedule or cancel from their confirmation emails or the Booking Page, so a custom site should put a clear line in its own confirmation telling them to use the link in Setmore's email. The missing webhooks are the one developers notice: to react to new bookings, either poll the appointments endpoint on a schedule or use a Zapier trigger, which needs Pro.

One thing to check first. The help article on API access says the API can create, update and cancel appointments and retrieve customer and staff data ^[1], while the published specification lists creation and label updates only. The specification is newer and precise about formats, so treat it as the contract, but ask api@setmore.com which is current before you design around either. Finally, there is no marketplace. Setmore says integrations cannot currently be sold or shared, so agencies can build for their own clients but cannot list an app for every Setmore user.

Building a custom booking front end

Before writing code, check whether an embed or a direct link does the job. The developer page names three routes: an HTML embed, a React integration or a fully custom front end. The embed needs no API at all, because the Booking Page embeds as an iframe that opens in a pop-up, and direct links pre-select a service and a team member. Both already handle payments and policies. Choose the API only when the embed's design cannot be made to fit, or when you want a white-label tool with Setmore out of view entirely; the Booking Page itself only drops the Setmore name on Pro. When the API is the right call, the flow runs in five steps.

1. List services and show durations and prices.
2. Ask for a date and fetch slots for the chosen staff and service.
3. Search for the customer by email and create one if missing.
4. Post the appointment in UTC.
5. Show a confirmation.

Done in that order, the steps make a complete booking engine. Setmore still sends the confirmation and reminder emails, and the appointment appears on the right staff calendar the moment the final call succeeds. Payments are not in the API, so take payment in your own checkout.

Other jobs: CRM sync, dashboards and label workflows

The customer search and create calls let a script copy contacts between Setmore and another system. For common CRMs, though, native connectors already exist: HubSpot syncs both ways, while Salesforce and Keap receive new contacts one way. Zoho CRM connects with an auth token, and Insightly and MailerLite with their own API keys. Some integrations, such as Freshdesk, also ask for a Setmore API key during setup. Those keys serve that plugin and are separate from the developer refresh token.

For reporting, the appointments endpoint, filtered by staff and paged by cursor, feeds a utilization dashboard; combine it with service durations to compute booked hours per person. Setmore's own reports export to XLS from the browser, which may be enough for a monthly review. Labels open a third use. An outside system can mark a visit as Paid after an invoice clears, or as Done after a form is completed, and staff see the status on the calendar block.

Zapier, the no-code alternative

Zapier connects Setmore to thousands of apps without code. Appointment triggers need Pro, and class bookings are not supported. Zapier can create Setmore contacts from another app and import appointments through a Create Appointment action, and its Appointment Deleted trigger fires when a booking is canceled or deleted. That trigger fills the gap left by the missing webhooks. A business that wants to free a room in a facilities tool after a cancellation gets what a webhook would do, without a server to maintain.

So the split is simple. Use Zapier when you need to react to cancellations, when the other app already has a Zapier connector, or when nobody on the team writes code. Use the API when you need a custom booking interface or bulk reads of appointments.

Security, health data and support

Keep the refresh token on a server, never in browser code. Because it never expires on its own, losing it is worse than losing a password, so keep it in a server-side secret store, never commit it to a code repository, and ask api@setmore.com what to do if it ever leaks. Turn on two-factor authentication on the account that owns the token. Card details never pass through the Setmore API; payments run through Stripe or the other processors.

Clinics need one more check. Setmore Health accounts handle patient data under a Business Associate Agreement, but the API documentation does not say whether API traffic falls within it. Confirm in writing before building on patient records, and keep Zoom out of it, since Setmore says Zoom is not HIPAA compliant. Developer questions go to api@setmore.com and general ones to help@setmore.com, and the developer page says a 24/7 human support team handles API questions.

How it compares with Calendly, Acuity and Square

For event-driven work, Setmore is behind its rivals. Calendly's API offers webhook subscriptions for events such as invitee created or canceled, scoped to an organization, user or group, and retries failed webhooks for 24 hours before disabling them. Acuity's API uses HTTP Basic authentication with a user ID and API key, must be called from a server, and fires signed webhooks on scheduling, rescheduling and cancellation. Square Appointments includes a Bookings API that lets an outside application create, update and cancel every booking on the calendar, which covers what Setmore leaves out. Businesses already on Square payments may prefer it.

The bottom line

Setmore's API is enough for a custom booking front end and for reading schedules into other systems. It is thin for anything event-driven: no webhooks, no reschedule or cancel, no sandbox. Before you build, confirm Pro on the live account, store the refresh token on a server, open a test account and decide how you will handle cancellations without an API call. Pair it with Zapier for cancellations. If your integration lives on events, choose a rival.