You can use Capable Health to manage Appointments between your Patients and members of your care team. Practitioners on your team can schedule Appointments on behalf of Patients in the Capable Health portal, or you can give Patients the ability to schedule Appointments directly in your application by using the Capable API.

Capable offers an integration with Acuity for the scheduling functionality. (Video calls for Appointments don’t require an integration — they’re built directly into the Capable platform.) Below, we walk through the steps necessary to configure the integration with Acuity and build scheduling into your app.

Set up the integration with Acuity

First, you’ll need to create an account directly with Acuity. Please note: You must choose the Powerhouse plan, which unlocks the ability to connect to Capable via Acuity’s API and enables HIPAA compliance. Please reach out to Acuity directly and ask them to sign a BAA, if applicable to your business.

It is highly recommended to create two separate accounts — one for testing purposes and one as your production environment. To create a sandbox account for testing, create a new account in Acuity first. Then, contact Acuity Support to ask them to convert the account into a developer sandbox. You can use the message template below for the support request:

Hi there!

I'm working with a platform called Capable Health to launch my digital health app,
and they're using Acuity to power their scheduling functionality. I've set up an
Acuity trial account, and I was hoping to get it converted to a developer account 
that I can use to test in my sandbox environment.

The account info is below:
Domain: [account domain]
Email: [the email you signed up with]

Please let me know if there's anything else you need from me to get this set up.

Thanks!

Note: You can find your domain in the URL search bar once you're logged into your Acuity account (you don't need anything after the ".com"):

When you're ready to launch in production, simply create a new Acuity account and follow the same setup instructions below.

Add your Acuity credentials to Capable

To create the integration between Acuity and Capable Health, you first need to generate API credentials from your Acuity admin portal. On the Integrations page of your Acuity portal, navigate to the API section and click “View credentials”.

Then, go to the Capable Health admin portal, to the Integrations page, and enter the Acuity User ID and API Key you just generated.

Credentials = Acuity User ID
Credentials Secret = Acuity API Key

Configure your Acuity account

Set your basic availability in Acuity

Before you can accept Appointments, you'll need to set your Practitioners’ availability, i.e., the times when users can book Appointments. These limits apply to Appointments booked through the Capable Health portal or via the Capable API.

In your Acuity portal, navigate to “Availability” under “Business Settings”. Select “Edit Default Limits” to set the default availability for your team. To learn more, visit Managing availability and calendars in the Acuity docs.

Please note: Later, you’ll create different Calendars in Acuity, and each Calendar can have its own custom availability settings.

Add Appointment Types in Acuity

Next, you’ll need to create Appointment Types for the different services you offer. Patients usually begin the scheduling process by choosing the type of Appointment they want to book. We recommend naming them generically, e.g., “Virtual Therapy Session” or “Virtual Nutritionist Consultation”, since you’ll be able to retrieve the Practitioner name and Appointment length from the Capable API when displaying Appointments for Patients.

In your Acuity portal, navigate to “Appointment Types” under “Business Settings”. Select “New Type of Service” and enter the Appointment Type details:

Name (required): This name will be displayed when booking Appointments through the Capable Health portal or via the Capable API.
Duration (required): The duration of an Appointment Type will be used to populate available times when booking through the Capable Health portal or via the Capable API.
Price (optional): Not currently exposed in Capable API
Category (optional): Not currently exposed in Capable API
Picture (optional): Not currently exposed in Capable API
Access: Leave default selection

To learn more, visit Creating and editing appointment types in the Acuity docs.

Add and manage Calendars in Acuity

Each Calendar in Acuity represents a separate set of hours when Patients can book Appointments. If you have multiple staff members who accept Appointments, you should create individual Calendars for each staff member.

First, make sure you’ve added all your Appointment Types following the directions above.

Then, in your Acuity portal, navigate to “Availability” under “Business Settings”. Select “Add New Calendar” and enter the Calendar details:

Calendar Name (required): The name of the Practitioner
Description (optional): Not currently exposed in Capable API
Location: ⚠️ Must leave blank
Image (optional): Not currently exposed in Capable API
Time Zone (required): The time zone your Practitioner operates in
Email / Phone Notification (required): The Practitioner’s email address. ⚠️ Note: This email must be the same exact one they use to log into the Capable Health portal.
Send Replies To (required): This can be the email of a care coordinator or admin and is required by Acuity.

Next, select the Appointment Types for this Calendar. If an Appointment Type is enabled for a specific Calendar, it means the Calendar accepts Appointments of that Appointment Type.

For example, let’s say you have a Calendar called “Dr. Kariko” and an Appointment Type called “Virtual Consultation”. If you enable the “Virtual Consultation” Appointment Type on the “Dr. Kariko” Calendar, a “Virtual Consultation” Appointments could then be made on that Calendar.

To learn more, visit Managing availability and calendars.

Set up the Location form

⚠️ The following configuration in Acuity is a necessary step for using Capable’s scheduling functionality.

A unique video call link will automatically be generated for every Appointments. To enable this functionality, you’ll need to configure Acuity to support a video call link as a location.

First, make sure you’ve added all your Appointment Types.

Then, in your Acuity portal, navigate to “Intake Form Questions” under “Business Settings”. Select “New Custom Form”.

Enter the following:

Form Name (required): “location” ⚠️ This must be entered exactly as shown (without the quotation marks)

This form is for internal use only, don't show it to clients: Yes (checked)

Then, under “Add Questions,” select “Address” and enter the following:

Question (required): “location” ⚠️ This must be entered exactly as shown (without the quotation marks)

Use this address as the location for the appointment: Yes (checked)
Description (optional): Not currently exposed in Capable API

Finally, under “Show this form when scheduling,” check the box next to every Appointment Type and save the form. ⚠️ This is a required step and will ensure that an Appointment will be successfully created for every Appointment Type.

Set up the metadata form

⚠️ The following configuration in Acuity is a necessary step if you want to store metadata on appointments.

First, make sure you’ve added all your Appointment Types.

Then, in your Acuity portal, navigate to “Intake Form Questions” under “Business Settings”. Select “New Custom Form”.

Enter the following:

Form Name (required): “metadata” ⚠️ This must be entered exactly as shown (without the quotation marks)

This form is for internal use only, don't show it to clients: Yes (checked)

Then, under “Add Questions,” select “Textbox” and enter the following:

Question (required): “metadata” ⚠️ This must be entered exactly as shown (without the quotation marks)

Description (optional): Not currently exposed in Capable API

Finally, under “Show this form when scheduling,” check the box next to every Appointment Type and save the form. ⚠️ This step enables you to store for metadata on every Appointment Type.

Managing Acuity email notifications

Acuity has built-in, automated emails that can be used to notify Patients about new, upcoming, rescheduled and cancelled Appointments. While you can set up your own custom emails in a separate communication tool such as Iterable or Braze using Capable’s scheduling events, using Acuity’s emails can be a low-lift option for sending Patients Appointment notifications.

There are several important considerations if you choose to use Acuity’s automated emails:

We highly recommend that you remove the “Change/Cancel Appointment” link at the bottom of every email template. This link directs to the Acuity client scheduler; find more detail on the risks of sharing Acuity client scheduler with your Patients below. To remove, navigate to a template in Email Settings, highlight the text, and delete.

Then, we recommend that you add a sentence in the body of every email template letting your Patients know how they can cancel or reschedule an Appointment. E.g. “To cancel or reschedule this appointment, please log into your [company name] account or email us at [email protected]”

You can take advantage of Acuity’s email template editor to customize the look-and-feel as well as wording for each email type. One edit you may consider making is deleting the “Powered by Acuity Scheduling” logo at the bottom of every email.

A note on Acuity’s scheduler

Acuity has a built-in “client scheduler” that can be accessed through a direct link or embedded as an iframe. From Acuity’s perspective, the purpose of this scheduler is to give their customers a way to enable clients to book appointments themselves, without the need for custom code.

Direct links

While we understand the value in being able to easily share a direct scheduling link, ⚠️ we highly advise against sharing any Acuity scheduling links with your Patients. If you do so, there is a risk that an appointment will not be successfully associated with a Patient in Capable if the Patient enters an email into the scheduler that does not match their Patient record.

Embedding the scheduler

Embedding the Acuity scheduler into your Patient-facing app may be an attractive option over other custom-code alternatives. If you’d like to explore this option, please contact us directly and we can talk you through the process.

Creating a Patient-facing experience

Your Practitioners and admins can create Appointments on behalf of Patients in the Capable Health portal. But you can also allow Patients to manage Appointments themselves in your app, by using our API to create a Patient-facing experience.

❗️
Please note: Capable currently only supports one Patient per Appointment.

Retrieving your Appointment Types & Calendars

Before a Patient can make an Appointment, they’ll need to see the available Appointment Types and Calendars. Use the the /appointment_types endpoint and /calendars endpoint to fetch them.

Retrieving available Appointments

Once you have the Appointment Types and Calendars that you want to display to your Patient, you can retrieve available Appointments for them using our /availability endpoint.

The endpoint requires an appointment_type_id and optionally accepts a calendar_id param. If you pass only an appointment_type_id, you’ll receive the available Appointments for all Calendars that contain the specified Appointment Type.

You can receive a maximum of seven consecutive days worth of available Appointments with one call to this endpoint, using the from_date and to_date parameters.

Creating an Appointment

To create an Appointment, pass the relevant patient_id, appointment_type_id, from_date and, optionally, a calendar_id to the POST /appointments endpoint.

The from_date parameter, despite the name, should actually be the specific date and time of the desired Appointment. Use the from_date value provided in one of the Appointment objects retrieved in the previous step.

If you don’t specify a calendar_id when creating an Appointment, the Appointment will be made on a randomly chosen Calendar that is associated with the Appointment Type and contains the requested time slot.

Retrieving a Patient’s Appointments

You can retrieve a Patient’s Appointments with the GET /appointments endpoint.

You can optionally specify scheduled_before and scheduled_after parameters to receive Appointments for a certain period of time. If you don’t specify either parameter, you’ll receive all the Patient’s booked Appointments.

Canceling an Appointments

To cancel an Appointment, simply pass the Appointment ID to the /appointments/{id}/cancel endpoint.

Rescheduling an Appointment

To reschedule an Appointment, simply pass the Appointment ID and from_date to the /appointments/{id}/reschedule endpoint. When rescheduling an Appointment, the Appointment remains associated with the same Calendar it was originally scheduled on.