Documentation Bookings and calendars Acuity Scheduling

Bookings integration

Acuity Scheduling

Acuity Scheduling integration overview
  • CategoryBookings
  • AuthHTTP Basic

Overview

Acuity Scheduling connects from Integrations in the MessageMind dashboard. The Connect Acuity Scheduling modal asks for the numeric User ID and API Key from Acuity, Integrations, API, View Credentials. Your Acuity account must include API access. MessageMind uses HTTP Basic authentication, previews eligible appointment types, and lets you select the types the AI may offer before saving the connection. Offered types must be active, public and priced at zero. The AI can check availability, collect attendee details and intake answers, submit appointments, and reschedule or cancel existing appointments.

What MessageMind can do with it

  • Offer the saved selection of active, public Acuity appointment types with a finite price of exactly zero.
  • Check live availability for a selected appointment type on a requested date or across a date range.
  • Collect the attendee's first name, last name, email, optional phone number and required intake-form answers.
  • Submit an appointment on the selected appointment type and report the booking result.
  • Find an appointment by attendee email, type, date and time to reschedule or cancel it from the conversation.
  • Reopen the appointment-type selector and save a different selection without re-entering the User ID and API Key.

Requirements

  • An Acuity Scheduling account with API access, currently offered on its Premium or Powerhouse plan.
  • The numeric User ID and the API Key copied from Acuity, Integrations, API, View Credentials.
  • At least one active, public appointment type priced at zero, selected for the MessageMind connection.
  • A MessageMind plan on Starter, Professional or Enterprise (the Acuity card on /integrations is plan-gated).

How to connect

  1. In Acuity, open Integrations, API, View Credentials and copy the numeric User ID and the API Key.
  2. In the MessageMind dashboard, open /integrations and click the Acuity card. The 'Connect Acuity Scheduling' modal opens with the description 'Enter your Acuity User ID and API Key to connect. Both are found under Acuity, Integrations, API, View Credentials. Your credentials stay encrypted on MessageMind.'
  3. In the User ID field (placeholder 'e.g. 12345678') paste the numeric Acuity User ID. The field tooltip reads 'Your numeric Acuity User ID. Find it in Acuity, Integrations, API, View Credentials.'
  4. Paste the API Key into the password field. Acuity's API access is available on its Premium or Powerhouse plan; the dashboard tooltip currently uses the Powerhouse name.
  5. Click Integrate to preview the eligible appointment types through POST /integration/acuity/preview. Preview validates the credentials and opens the selector; it does not save the connection yet.
  6. The appointment-type checklist shows active, public types priced at zero. Paid, private, inactive and missing-price types are excluded. If none qualify, the toast reads 'No free appointment types found on your Acuity account. Paid types aren't supported yet.'
  7. Select at least one eligible appointment type and submit the selection. The first connection is saved through POST /integration/setup, with 'Connecting to Acuity...' followed by 'Acuity Connected!' on success. Later settings changes use /integration/acuity/update-meetings.

Authentication and permissions

Mechanism
HTTP Basic authentication against Acuity's REST API using the Acuity User ID as the username and the API Key as the password. There is no OAuth flow and no refresh token; credential rotation is manual.
Credentials
User ID and API Key stored on your MessageMind tenant and sent as the Authorization header on every call to Acuity.

Available data and actions

Reads

  • The connected Acuity account profile, including its name and time zone.
  • Appointment types and their id, name, duration and price, filtered to the saved eligible selection.
  • Applicable intake forms and their fields; forms marked hidden are excluded.
  • Live available times for the selected appointment type and requested date or date range.
  • Appointments matched by attendee email, type, date and time for rescheduling or cancellation.
  • A settings-preview response containing the current eligible catalog, saved selection and any previously selected types that no longer qualify; the dashboard can reuse a cached response during the same page session.

Writes

  • The initial credentials and selected appointment types through /integration/setup; later selection changes through /integration/acuity/update-meetings.
  • New appointments on the selected appointment type, with first name, last name, email, optional phone and required intake-form answers.
  • Rescheduled appointments to a new time on the same type.
  • Cancelled appointments by id, with a cancel note.

AI agent use cases

  • Let a client book a free consult, intro call or discovery session on Acuity from a WhatsApp or Instagram thread, with the AI picking from the free types you ticked.
  • Give the AI a curated subset of your free Acuity appointment types so it never offers an internal or paid one by accident.
  • Refresh the appointment-type picker with a settings-preview request to identify types that were removed or no longer qualify. Reload the dashboard to clear its in-memory preview cache.
  • Reschedule or cancel an appointment from the conversation using the attendee email, type, date and time to find it.

Configuration

  • The AcuityMeetingsCheckList is the single configuration surface: tick the free appointment types the AI is allowed to book on and save. Non-ticked types are invisible to the AI.
  • Paid appointment types are filtered out at /acuity/preview time. The dashboard notice reads verbatim 'Only free appointment types are available. Paid types aren't supported yet.'
  • Settings-preview compares the saved selection with the live eligible catalog when a request is made. Reopening settings can use the in-memory cached response; reloading the dashboard clears that cache. Saving validates the selected types against the current catalog.
  • There is no bring-your-own OAuth app: the connection is a single User ID + API Key pair you paste in the modal.
  • The current connector books the selected appointment type without a separate calendar or staff-selection setting.
  • Availability searches use the requested date or date range. A time-only search scans the next 14 days; a requested date range scans up to 31 days. Nearest-slot searches check the current month and then the next month if needed.
  • Bookable appointment types are limited to the saved selection of active, public types whose price is exactly zero. Paid, private, inactive and missing-price types are excluded.
  • The connector collects applicable intake-form fields and excludes forms marked hidden. Required fields must be supplied before booking.

Example workflows

First-time connect and appointment-type selection

  1. On /integrations click the Acuity card. The 'Connect Acuity Scheduling' modal opens.
  2. Paste the Acuity User ID and the API Key from Acuity, Integrations, API, View Credentials, then click Integrate.
  3. The dashboard calls POST /integration/acuity/preview and opens the appointment-type selector when eligible types are returned. This preview has not saved a connection yet.
  4. Tick the free appointment types the AI should offer in chat. The notice 'Only free appointment types are available. Paid types aren't supported yet.' is shown above the list.
  5. Select at least one eligible type and save. POST /integration/setup stores the credentials and selected IDs; the success toast is 'Acuity Connected!'.

Reopening the Acuity settings panel

  1. Open the Acuity settings modal from /integrations.
  2. The dashboard uses a cached settings preview when available. Otherwise POST /integration/acuity/settings-preview reads the current catalog and saved selection. Reload the dashboard to clear the in-memory cache.
  3. The returned eligible types are shown with the saved selection. When a fresh response identifies removed or unavailable selected types, a notice explains that they have been removed from the selection.
  4. Adjust the ticks and save to re-run update-meetings against the fresh list.

Book an Acuity appointment from a chat thread

  1. Client asks when they can come in for a specific appointment type.
  2. The AI checks live availability on the matching type and quotes an open slot in the business's time zone.
  3. The AI collects the attendee's first name, last name, email and optional phone number.
  4. The AI asks the intake-form questions the type requires and confirms the slot back.
  5. The AI submits the appointment and reports the result. If Acuity returns a confirmation page, the customer receives that link.

Limitations

  • Only free appointment types are available. Paid types aren't supported yet.
  • The Acuity account must provide API access for the credentials. Acuity currently lists this on Premium or Powerhouse.
  • There is no OAuth flow. Credential rotation is manual: regenerating the API Key in Acuity means pasting the fresh key into the Acuity card on /integrations.
  • The connection is a User ID + API Key pair; there is no bring-your-own OAuth app.
  • Availability can change between the check and the booking request. If Acuity rejects the booking, check availability again before choosing another slot.
  • Paid appointments and deposit collection are not supported by the current Acuity booking selection.

Troubleshooting

A toast reads 'No free appointment types found on your Acuity account. Paid types aren't supported yet.' and the AcuityMeetingsCheckList is empty.

Create at least one active, public appointment type in Acuity with its price set to zero and preview again. Paid, private, inactive and missing-price types are excluded.

A toast reads 'Failed to fetch Acuity appointment types.' during the first connect.

The preview request failed. Confirm the User ID is the numeric value from Acuity, Integrations, API, View Credentials, that the API Key is complete, and that the Acuity account includes API access.

A toast reads 'Your saved Acuity credentials are no longer valid. Please reconnect.'

Acuity rejected the stored HTTP Basic credential during a settings-preview load. The API Key has been rotated or revoked in Acuity. Regenerate the API Key in Acuity, Integrations, API, View Credentials and paste the fresh value into the Acuity card.

A toast reads 'Failed to load Acuity settings.' when reopening the Acuity modal.

The settings-preview request failed. Retry after reloading the dashboard; if the problem persists, confirm API access and that the saved User ID and API Key remain valid.

A previously selected appointment type no longer appears in the AcuityMeetingsCheckList.

The type may have been deleted, disabled, made private or given a nonzero price. A fresh settings-preview response excludes types that no longer qualify. Select a currently eligible type and save.

Disconnect and reconnect

  • In Integrations, use the Acuity disconnect control to remove the MessageMind connection. Appointments already created in Acuity are unaffected.
  • Appointments already written to Acuity stay on the business's calendar; disconnecting does not cancel them.
  • To reconnect, paste the User ID and API Key again from Acuity, Integrations, API, View Credentials and pick the free appointment types in the AcuityMeetingsCheckList.