A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Acuity Scheduling API is how an app or AI agent works with an appointment-booking account: checking open availability, booking an appointment, rescheduling or canceling it, and managing clients, appointment types, and coupon or package certificates. Access is granted through a User ID and API key, or an OAuth token, and that one credential reaches the whole account, because the API has no per-resource permissions to narrow it. It can also push events to a webhook URL when an appointment is booked, rescheduled, or canceled.
How an app or AI agent connects to Acuity Scheduling determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the credentials behind it.
The REST API answers at https://acuityscheduling.com/api/v1 over HTTPS. It is a single version, v1, with no dated version header to pin.
Webhooks post a form-encoded event to a target URL when an appointment is scheduled, rescheduled, canceled, or changed, or an order is completed. Subscriptions are created through the API or set in account settings, and each delivery is signed so it can be verified as coming from Acuity Scheduling.
Authentication is done over SSL with HTTP Basic, using the numeric User ID as the username and the API key as the password. The credentials are found in the account's Integrations settings and carry full access to that one account's v1 API.
OAuth 2.0 lets an app connect to many Acuity Scheduling accounts without holding each one's API key. The authorization flow requests the single api-v1 scope and returns a bearer access token. That one scope covers all of v1, so it is not a way to narrow what the token can reach.
The Acuity Scheduling API is split into areas an agent can act on, like appointments, availability, clients, appointment types, and certificates. Each area has its own methods, and a write can book an appointment, cancel one, or create a client record.
List and read appointments, create new ones, update their details, reschedule and cancel them, and read the payments on an appointment.
Find open dates and times for an appointment type, list class times, and check whether specific times are still available before booking.
List the client records on an account, create a new client, and edit an existing client.
List the appointment types offered, the products for sale, and the intake forms attached to bookings.
List package and coupon certificates, create a new certificate, and delete one.
List the calendars on an account and read the authenticated account's own details.
List the webhook subscriptions on an account, create a new subscription, and delete one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AppointmentsList and read appointments, create new ones, update their details, reschedule and cancel them, and read the payments on an appointment.7 | ||||||
| GET | /appointments | Get a list of appointments currently scheduled for the authenticated user. | read | api-v1 | Current | |
Filterable by date range, calendar, appointment type, and client fields. OAuth grants the single api-v1 scope, which covers all of v1; HTTP Basic with a User ID and API key has the same reach. Acuity does not offer per-resource scopes. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /appointments/:id | Get a single appointment by its ID. | read | api-v1 | Current | |
Returns the appointment's time, client details, and intake form answers. The api-v1 scope covers this; there is no narrower read-only permission. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /appointments | Create an appointment. Requires datetime, appointmentTypeID, firstName, lastName, and email. | write | api-v1 | Current | |
Passing admin=true disables availability and attribute validations and allows setting notes, and then requires a calendarID. Validation failures return 400 with codes like not_available or required_email. The api-v1 scope covers this write. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook event appointment-scheduledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /appointments/:id | Update an appointment's details from a white-list of updatable attributes. | write | api-v1 | Current | |
Only white-listed fields change here; time changes go through the reschedule endpoint. The api-v1 scope covers this write. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook event appointment-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /appointments/:id/reschedule | Reschedule an appointment to a new time, with availability validation unless admin is set. | write | api-v1 | Current | |
A separate endpoint from update, because moving the time runs its own availability checks. The api-v1 scope covers this write. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook event appointment-rescheduledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /appointments/:id/cancel | Cancel an appointment. | write | api-v1 | Current | |
Canceling is a dedicated endpoint, not a state field on update. The api-v1 scope covers this write. Acts onappointment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook event appointment-canceledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /appointments/:id/payments | Retrieve a list of payment transactions for a particular appointment. | read | api-v1 | Current | |
Returns the amounts and transaction records tied to one appointment. The api-v1 scope covers this read. Acts onpayment Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AvailabilityFind open dates and times for an appointment type, list class times, and check whether specific times are still available before booking.4 | ||||||
| GET | /availability/dates | Return available dates in a month for an appointment type, to use together with the times endpoint when booking. | read | api-v1 | Current | |
Read-only; takes month and appointmentTypeID. The api-v1 scope covers this read. Acts onavailability Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /availability/times | Return available times for a date and appointment type. | read | api-v1 | Current | |
Read-only; takes date and appointmentTypeID, optionally a calendarID. The api-v1 scope covers this read. Acts onavailability Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /availability/classes | Return scheduled class times for a date and appointment type, including their remaining open slots. | read | api-v1 | Current | |
Read-only; classes are group appointment types with multiple attendees. The api-v1 scope covers this read. Acts onavailability Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /availability/check-times | Check whether one or more specific times are still available for an appointment type before booking. | read | api-v1 | Current | |
A POST that validates candidate times and changes nothing, so it reads rather than writes. The api-v1 scope covers it. Acts onavailability Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ClientsList the client records on an account, create a new client, and edit an existing client.3 | ||||||
| GET | /clients | Get a list of clients on the account, with an optional search filter. | read | api-v1 | Current | |
Returns names, emails, and phone numbers, so it exposes client contact details. The api-v1 scope covers this read. Acts onclient Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /clients | Create a new client record. Requires firstName and lastName. | write | api-v1 | Current | |
Adds a contact to the account's client list. The api-v1 scope covers this write. Acts onclient Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /clients/:id | Edit an existing client record. | write | api-v1 | Current | |
Updates the stored contact details for one client. The api-v1 scope covers this write. Acts onclient Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Appointment types & productsList the appointment types offered, the products for sale, and the intake forms attached to bookings.3 | ||||||
| GET | /appointment-types | Get a list of the appointment types offered on the account, including their duration and price. | read | api-v1 | Current | |
An appointment type defines a bookable service; classes are appointment types with multiple attendees. The api-v1 scope covers this read. Acts onappointment type Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /products | Get a list of the products for sale on the account. | read | api-v1 | Current | |
Products are sellable items like packages and gift certificates configured on the account. The api-v1 scope covers this read. Acts onproduct Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /forms | Get a list of the custom intake forms and their fields configured on the account. | read | api-v1 | Current | |
Returns the form questions clients answer when booking, which the appointment endpoints reference by field ID. The api-v1 scope covers this read. Acts onform Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Certificates & couponsList package and coupon certificates, create a new certificate, and delete one.3 | ||||||
| GET | /certificates | Get a list of package and coupon certificates on the account. | read | api-v1 | Current | |
Returns redeemable codes, the products they apply to, and any remaining uses or expiry. The api-v1 scope covers this read. Acts oncertificate Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /certificates | Create a package or coupon certificate. | write | api-v1 | Current | |
Mints a redeemable code that carries monetary value against products or appointment types. The api-v1 scope covers this write. Acts oncertificate Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /certificates/:id | Delete a certificate. | write | api-v1 | Current | |
Removes a redeemable code from the account. The api-v1 scope covers this write. Acts oncertificate Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Calendars & accountList the calendars on an account and read the authenticated account's own details.2 | ||||||
| GET | /calendars | Get a list of the calendars on the account, one per staff member or resource. | read | api-v1 | Current | |
Calendars are used to filter availability and appointments and to route bookings to a person. The api-v1 scope covers this read. Acts oncalendar Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me | Get basic information about the authenticated account, including its ID, email, timezone, currency, and plan. | read | api-v1 | Current | |
Identifies which account a token or key belongs to. The api-v1 scope covers this read. Acts onaccount Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the webhook subscriptions on an account, create a new subscription, and delete one.3 | ||||||
| GET | /webhooks | List the webhook subscriptions currently active on the account. | read | api-v1 | Current | |
Shows each subscription's event and target URL. The api-v1 scope covers this read. Acts onwebhook Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Create a webhook subscription for an event, delivered to a target URL on port 443 or 80. | write | api-v1 | Current | |
An account is capped at 25 webhooks, and creating a 26th returns a 400. The api-v1 scope covers this write. Acts onwebhook Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/:id | Delete a webhook subscription and stop its notifications. | write | api-v1 | Current | |
Removes one subscription so its events stop being delivered. The api-v1 scope covers this write. Acts onwebhook Permission (capability) api-v1VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Acuity Scheduling can notify an app or AI agent when something happens, like an appointment being booked, rescheduled, or canceled, by posting an event to a webhook URL. A subscription is created through the API or set in account settings, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
appointment.scheduled | Fires once when an appointment is initially booked. | /appointments |
appointment.rescheduled | Fires when an appointment is rescheduled to a new time. | /appointments/:id/reschedule |
appointment.canceled | Fires whenever an appointment is canceled. | /appointments/:id/cancel |
appointment.changed | A catch-all that fires when an appointment is changed in any way, including booking, rescheduling, and canceling. | /appointments/appointments/:id/appointments/:id/reschedule/appointments/:id/cancel |
order.completed | Fires when an order is completed, such as a package, gift certificate, or subscription purchase. | In-app only |
Acuity Scheduling limits how fast an app or AI agent can call, by a per-IP request rate measured each second together with a cap on concurrent connections, and returns a 429 when either is exceeded.
Acuity Scheduling limits requests per IP address, to around 10 requests per second with at most 20 concurrent connections. Passing either returns a 429 with a JSON body carrying status_code, error set to too_many_requests, and a message. There is no documented per-method cost or hourly quota; the limit is the per-second rate and the concurrency cap. An integration should space its calls and retry after backing off when it sees a 429.
List endpoints such as appointments take a max parameter that defaults to 100, with minDate and maxDate to window a date range and other filters like calendarID and appointmentTypeID to narrow results. There is no documented cursor or page-token scheme; results are bounded by the max parameter and the supplied filters.
Requests and responses are JSON, except webhook deliveries, which arrive as form-encoded POSTs. Datetime values must be parseable by PHP's strtotime, and timezones use IANA identifiers such as America/New_York. No single overall payload size limit is documented.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | Validation failed. The body holds an error code and a human-readable message, with codes such as not_available, required_email, invalid_certificate, or no_available_calendar. Creating a 26th webhook also returns 400. | Read the error code and message, correct the named field or condition, and resend. |
| 401 | Unauthorized | Authentication failed. The User ID and API key, or the OAuth token, is missing or invalid. | Check the credentials and the Authorization header, then send valid credentials. |
| 429 | too_many_requests | A rate limit was exceeded. Acuity allows about 10 requests per second and 20 concurrent connections per IP address, and returns a body with status_code, error, and message when either is passed. | Back off and retry, spacing requests and limiting how many run at once. |
Acuity Scheduling runs a single version of its API, v1, rather than dated versions, and ships new capabilities additively, like the dynamic Webhooks API for creating subscriptions through the API.
Acuity Scheduling serves one version of its API, v1, at https://acuityscheduling.com/api/v1. There is no dated version header and no parallel older version, so integrations do not migrate between versions. New capabilities are added to v1 additively, like the dynamic Webhooks API, which lets subscriptions be created, listed, and deleted through the API rather than only in account settings.
There is no version header to pin; new endpoints are added to v1 over time.
Acuity developer docs ↗Bollard AI sits between a team's AI agents and Acuity Scheduling. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.