Acuity Scheduling Data Source

Acuity Scheduling is cloud-based appointment scheduling software for service businesses. Follow the instructions below to create a new data flow that ingests data from an Acuity Scheduling source in Nexla.

Acuity Scheduling

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Acuity Scheduling connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Acuity Scheduling instance, and click Next; or, create a new Acuity Scheduling credential for use in this flow.

3. In Nexla, Acuity Scheduling data sources can be created using pre-built endpoint templates, which expedite source setup for common Acuity Scheduling endpoints. Each template is designed specifically for the corresponding Acuity Scheduling endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Acuity Scheduling sources can also be configured manually, allowing you to ingest data from Acuity Scheduling endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Acuity Scheduling endpoints. Each template is designed specifically for the corresponding Acuity Scheduling endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

  List Appointments

  This endpoint retrieves scheduled appointments from your Acuity Scheduling account. Use it to sync booking data into a warehouse or downstream system, build reporting on appointment volume and revenue, or feed appointment data into a CRM.

  • All filter parameters on this endpoint are optional. Leave them blank to return appointments using Acuity Scheduling's default behavior, or set specific values to narrow the result set.
  • Enter the maximum number of appointments to return per request in the Max field. The Acuity Scheduling default is 100 and the API caps this at 250.
  • Enter the earliest appointment date to include (in YYYY-MM-DD format) in the Min Date field, and the latest appointment date to include in the Max Date field. Date filtering is applied against the appointment's scheduled date.
  • To restrict results to a single calendar or appointment type, enter the corresponding ID in the Calendarid or Appointmenttypeid field. Calendar IDs can be obtained from the List Calendars endpoint, and appointment type IDs from List Appointment Types.
  • To filter by client information, enter values in the Firstname, Lastname, Email, or Phone fields. Phone numbers with a leading + must be URL-encoded as %2B (for example, +14155551212 becomes %2B14155551212).
  • To include or exclude canceled appointments, enter true or false in the Canceled field.
  • To filter by a custom intake-form field value, enter the desired value in the Custom Field Filter (field:ID) field. The corresponding form field ID is substituted into the URL parameter and can be obtained from the List Forms endpoint.
  • Set the Exclude Forms field to true to omit intake-form answers from each appointment record. Acuity Scheduling recommends enabling this for list operations because it significantly speeds up responses.
  • Use the Direction field to control the sort order of returned appointments (ASC or DESC).

  The Acuity Scheduling /appointments endpoint does not support offset/page parameters. To paginate, advance the Min Date filter to the latest returned appointment date and re-run the call. For additional reference, see the Acuity Scheduling pagination guidance.

  Get Appointment

  This endpoint retrieves the full record for a single appointment by ID. Use it to enrich an existing dataset of appointment IDs with the latest details, or to feed downstream systems that operate on individual appointments.

  • Enter the appointment ID in the Appointment Id field. This field is required. Appointment IDs can be obtained from the List Appointments endpoint or from upstream Nexla data flows.
  • Set the Include Past Form Answers field to true to include the client's historical intake-form answers from previous appointments, or leave it blank to return only the answers attached to this appointment.

  This endpoint returns a single appointment object (not an array). The path to data is set to the response root, so the appointment is treated as the record.

  List Appointment Types

  This endpoint returns all appointment types configured in the account — the services that clients can book. Use it to sync your service catalog into a warehouse or to populate downstream selectors.

  • Set the Includedeleted field to true to include soft-deleted appointment types, or leave it blank to return only active types.

  List Appointment Add-ons

  This endpoint returns all add-on services that clients can attach to an appointment. Use it to keep a catalog of available add-ons synced to a warehouse or downstream system.

  • No configuration is required for this endpoint beyond selecting it. All available add-ons are returned automatically.

  Get Appointment Payments

  This endpoint retrieves all payments associated with a specific appointment. Use it to reconcile revenue against bookings or feed billing data into accounting systems.

  • Enter the appointment ID in the Appointment Id field. By default, the template substitutes the upstream record's id attribute, so the endpoint can be driven by an upstream List Appointments source.

  Pair this endpoint with List Appointments as an upstream source to fetch payment details for every appointment in a defined date range.

  List Calendars

  This endpoint returns all calendars (staff or resources) on the account, including their names, IDs, timezones, and emails. Use it as a reference dataset for calendar IDs needed by other endpoints, or to sync staff/resource metadata.

  • No configuration is required for this endpoint beyond selecting it. All calendars on the account are returned automatically.

  Calendar IDs from this endpoint are required by other endpoints — including List Appointments, List Blocks, Get Available Dates, Get Available Times, and Get Available Classes — when filtering by calendar.

  List Clients

  This endpoint returns the client list for the account, optionally filtered by a free-text search term. Use it to sync your client base into a CRM, marketing platform, or warehouse.

  • To narrow the result set, enter a search term in the Search field. The search is matched against client name, email, and phone.
  • Leave the Search field blank to return all clients on the account.

  List Blocks

  This endpoint returns blocked-off (unavailable) time periods on calendars — vacations, breaks, or recurring unavailable slots. Use it to feed availability dashboards or sync downtime into other scheduling systems.

  • Enter the maximum number of blocks to return in the Max field, or leave it blank to use the Acuity Scheduling default.
  • To restrict results to a specific date range, enter the earliest date (in YYYY-MM-DD format) in the Mindate field and the latest date in the Maxdate field.
  • To restrict results to a single calendar, enter the calendar ID in the Calendarid field. Calendar IDs can be obtained from the List Calendars endpoint.

  List Labels

  This endpoint returns all labels available in the Acuity Scheduling account. Labels are used to tag and categorize appointments, and this endpoint exposes the full label catalog.

  • No configuration is required for this endpoint beyond selecting it. All labels on the account are returned automatically.

  List Forms

  This endpoint returns all intake forms configured in the Acuity Scheduling account, including each form's questions and field IDs. Use it to map intake-form responses to downstream systems or to look up field IDs needed by List Appointments.

  • No configuration is required for this endpoint beyond selecting it. All forms on the account are returned automatically.

  Field IDs from this endpoint are required to use the Custom Field Filter (field:ID) parameter on the List Appointments endpoint.

  Get Available Dates

  This endpoint returns the dates within a given month that have availability for a specific appointment type. Use it to surface available booking dates in a custom UI or downstream scheduling assistant.

  • Enter the target month (in YYYY-MM format, for example 2026-05) in the Month field.
  • Enter the appointment type ID in the Appointment Type ID field. Appointment type IDs can be obtained from the List Appointment Types endpoint.
  • Optionally, enter a calendar ID in the Calendar ID field to restrict results to a specific staff member or resource.
  • Optionally, enter add-on IDs in the Add-on IDs field to compute availability for an appointment that includes specific add-ons. Add-on IDs can be obtained from the List Appointment Add-ons endpoint. Repeat the parameter to pass multiple values.
  • Optionally, enter a timezone in the Timezone field (for example, America/New_York) to control how availability is calculated.

  Get Available Times

  This endpoint returns the available appointment times for a specific date, appointment type, and calendar. Use it after Get Available Dates to drill into time-slot availability for a chosen date.

  • Enter the target date (in YYYY-MM-DD format, for example 2026-05-15) in the Date field.
  • Enter the appointment type ID in the Appointment Type ID field.
  • Optionally, enter a calendar ID in the Calendar ID field to restrict results to a specific staff member or resource.
  • Optionally, enter add-on IDs in the Add-on IDs field to compute availability for an appointment that includes specific add-ons. Repeat the parameter to pass multiple values.
  • Optionally, enter a timezone in the Timezone field to control how times are returned.
  • To exclude specific existing appointments from the busy calculation, enter their IDs in the Ignore Appointment IDs field. This is used during a reschedule so the appointment being moved does not block its own slot.

  Get Available Classes

  This endpoint returns available class sessions for a specified month or date range. Use it to surface class schedules in a custom UI, sync upcoming classes into a warehouse, or feed downstream booking tools.

  • Restrict the time window by either entering a single month (in YYYY-MM format) in the Month field, or by entering both a Minimum Date and a Maximum Date (both in YYYY-MM-DD format).
  • Optionally, restrict results to a specific class type by entering the appointment type ID in the Appointment Type ID field, or to a specific calendar by entering the calendar ID in the Calendar ID field.
  • Optionally, enter a timezone in the Timezone field to control how class times are returned.
  • Set Include Unavailable to true to include classes that have no remaining capacity, and Include Private to true to include private classes that are not normally shown on the public booking page.

  List Certificates

  This endpoint returns certificates (gift certificates and coupons) issued in the account, optionally filtered by product, order, appointment type, or customer email. Use it to feed promotions data into downstream analytics or finance systems.

  • To restrict the result set, enter a value in one or more of the optional fields: Product ID, Order ID, Appointment Type ID, or Email.
  • Leave all fields blank to return all certificates issued on the account.

  List Orders

  This endpoint returns orders placed in the Acuity Scheduling account — for packages, subscriptions, gift certificates, or product purchases. Use it to sync revenue and order history into a warehouse or accounting system.

  • Enter the maximum number of orders to return in the Maximum Results field, or leave it blank to use the Acuity Scheduling default.

  Get Order

  This endpoint retrieves a single order by ID. Use it to enrich an existing dataset of order IDs with the full order details, including line items and payment status.

  • Enter the order ID in the Order ID field. Order IDs can be obtained from the List Orders endpoint.

  List Products

  This endpoint returns all products available in the Acuity Scheduling account — packages, subscriptions, and gift certificates that clients can purchase. Use it to keep a downstream catalog in sync.

  • Set the Deleted field to true to include soft-deleted products, or leave it blank to return only active products.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Acuity Scheduling data sources can be manually configured to ingest data from any valid Acuity Scheduling API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Acuity Scheduling sources, such as sources that chain calls to multiple endpoints — for example, listing appointments and then fetching the payment records for each.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Acuity Scheduling API from the Method pulldown menu. Most Acuity Scheduling read endpoints use GET:

   • GET: For retrieving data from the API (list and get endpoints)
   • POST: For sending data to the API or triggering actions
   • PUT: For updating existing data
   • DELETE: For removing data

API Endpoint URL

3. Enter the URL of the Acuity Scheduling API endpoint from which this source will fetch data in the Set API URL field. All Acuity Scheduling API URLs use the base https://acuityscheduling.com/api/v1/ followed by the resource path (for example, https://acuityscheduling.com/api/v1/appointments).

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods. They are particularly useful for Acuity Scheduling endpoints that filter on mindate, maxdate, month, or date parameters.

Macros are particularly useful for APIs that require date ranges or other dynamic values that change between data ingestion runs. For example, you can use {now-7} with a Day time unit to always fetch the last 7 days of appointments.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime

   • {now-1} – The datetime one time unit before the current datetime

   • {now+1} – The datetime one time unit after the current datetime

   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. Acuity Scheduling expects YYYY-MM-DD for date filters and YYYY-MM for the month parameter, so the format must match the endpoint being called.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that adapt based on existing data. For Acuity Scheduling, this is useful when you have a Nexla dataset of appointment IDs, order IDs, or calendar IDs and want to fetch the related record for each.

Lookup-based macros are useful when you need to create Acuity Scheduling URLs that reference specific IDs from another data source — for example, fetching payments for each appointment ID returned by a List Appointments source.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by an Acuity Scheduling endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) by specifying the path to the relevant data within the response.

Most Acuity Scheduling list endpoints (such as /appointments, /clients, /orders) return a top-level JSON array, so the path to data is $[*]. Endpoints that return a single object (such as /appointments/{id}) use $ to treat the entire response body as a single record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (for example, $[*] to access every element of a top-level array).
  Path to Data Example:

  For an Acuity Scheduling endpoint that returns a top-level array of appointments (for example, GET /appointments), enter $[*] as the path to data. For an endpoint that returns a single object (for example, GET /appointments/123), enter $.

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

Most Acuity Scheduling list endpoints return data as a top-level array without sibling metadata, so this setting is rarely required. It is most useful when integrating with custom Acuity Scheduling endpoints or downstream wrappers that include response envelopes.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (for example, header1:value1,header2:value2).

  You do not need to include any headers already present in the credentials. The Authorization header for Basic Auth or OAuth 2.0 is added automatically based on your Acuity Scheduling credential.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Acuity Scheduling data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.