Quick Start
Get started with Acuity's API quickly with an example in bash, PHP or JavaScript.
Authentication
Find your API credentials in Acuity under Integrations.
Authentication to the API is done over SSL with HTTP Basic Auth, using your numeric User ID for the username and your API Key for the password. 401 Unauthorized will be returned on authentication failure.
For information on connecting multiple Acuity accounts to your app, check out OAuth2 access.
Example
curl -u ACUITY_USER_ID:ACUITY_API_KEY "https://acuityscheduling.com/api/v1/appointments"var Acuity = require('acuityscheduling');
var acuity = Acuity.basic({
userId: ACUITY_USER_ID,
apiKey: 'ACUITY_API_KEY'
});
acuity.request('appointments', function (err, res, appointments) {
if (err) return console.error(err);
console.log(appointments);
});<?php
require_once('vendor/autoload.php');
$acuity = new AcuityScheduling(array(
'userId' => ACUITY_USER_ID,
'apiKey' => 'ACUITY_API_KEY'
));
$appointments = $acuity->request('appointments');
print_r($appointments);<?php
$userID = 'ACUITY_USER_ID';
$key = 'ACUITY_API_KEY';
// URL for all appointments (just an example):
$url = 'https://acuityscheduling.com/api/v1/appointments.json';
// Initiate curl:
// GET request, so no need to worry about setting post vars:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// Grab response as string:
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// HTTP auth:
curl_setopt($ch, CURLOPT_USERPWD, "$userID:$key");
// Execute request:
$result = curl_exec($ch);
// Don't forget to close the connection!
curl_close($ch);
$data = json_decode($result, true);
print_r($data);Making Cross Origin Requests and Using AJAX
You must make API requests from your own or an external server where you can store your API credentials securely. Acuity does not support cross origin requests as client side requests expose any authentication that you're using. You can expose specific endpoints on your server for the APIs you'd like to access over AJAX.
/appointments
Get a list of appointments currently scheduled for the authenticated user.
canceled=true
By default, canceled appointments are not returned. To retrieve canceled appointments, use the query ?canceled=true. To retrieve both canceled and scheduled appointments, you can use ?showall=true.
Canceled appointment responses include a noShow field which is true if the admin has marked the appointment as a no-show, and false if the appointment is simply canceled.
/appointments
Create an appointment.
Availability
When creating appointments, availability and forms are validated as if the appointment is being booked by a client by default. Use /availability/dates and /availability/times or /availability/classes to find available slots for an appointment type.
Booking as an Admin
admin=true
By default appointments are created as if they are being booked by a client. Booking as an admin disables availability and attribute validations, and allows setting the notes attribute. To book as an admin pass the query parameter admin=true.
POST "https://acuityscheduling.com/api/v1/appointments?admin=true"
{
"datetime": "2016-02-03T14:00:00-0800",
"appointmentTypeID": 1,
"firstName": "Bob",
"lastName": "McTest",
"notes": "My notes."
}Setting Forms
Form data may be set using the special fields attribute. The fields are an array of field ID and value objects, {"id": fieldId, "value": fieldValue}.
Field IDs can be found in the GET /forms API or by editing the form in Acuity and inspecting the fields by right clicking the field and choosing "Inspect".
Values for the multi-valued field checkboxlist should be submitted as a single comma-delimited string.
File intake form fields can be set with a string value for the location of the file. It isn't possible to actually upload files through our API, so you'll need to host or store the file outside Acuity.
POST "https://acuityscheduling.com/api/v1/appointments"
{
"datetime": "2016-02-03T14:00:00-0800",
"appointmentTypeID": 1,
"firstName": "Bob",
"lastName": "McTest",
"email": "bob.mctest@example.com",
"fields": [
{"id": 1, "value": "Party time!"}
]
}Certificates
Book appointments using coupons and package codes by setting the certificate attribute.
We'll check that the certificate is valid and may be applied to the appointment type before scheduling, but you can validate certificates ahead of time using the /certificates/check endpoint. Try out the /certificates endpoint to suggest certificates for a particular client.
Addons
Addons can add time and duration to an appointment before it is booked. Use /appointments-addons in order to retrieve the list of addons and their IDs before including the list of addonIDs in the POST appointment body while scheduling.
There are other availability considerations to factor in before using addonIDs when creating an appointment. Click here to for more details.
No Email
Don't send the confirmation e-mails or SMS by creating the appointment with the noEmail=true query parameter.
Errors
Availability and validation errors return a 400 error response:
{
"status_code": 400,
"message": "Attribute \"firstName\" is required.",
"error": "required_first_name"
}Each error has an error code and a human readable message describing what went wrong.
| Error | Message |
|---|---|
required_first_name |
Attribute "firstName" is required. |
required_last_name |
Attribute "lastName" is required. |
required_email |
Attribute "email" is required. |
invalid_email |
Invalid "email" attribute value. |
invalid_fields |
The field "1" does not exist on this appointment. |
required_field |
The field "4" is required. |
required_appointment_type_id |
The parameter "appointmentTypeID" is required. |
invalid_appointment_type |
The appointment type "987654321" does not exist. |
invalid_calendar |
The calendar "987654321" does not exist. |
required_datetime |
The parameter "datetime" is required. |
invalid_timezone |
Invalid timezone "Aint/No_Timezone". |
invalid_datetime |
The datetime "asdf" is invalid. |
no_available_calendar |
We could not find an available calendar. |
not_available_min_hours_in_advance |
The time "2016-01-05T16:00:00-0800" is not far enough in advance. |
not_available_max_days_in_advance |
The time "2017-02-07T16:00:00" is too far in advance. |
not_available |
The time "2016-03-08T05:00:00-0800" is not an available time slot. |
invalid_certificate |
The certificate "NOCODENOPROBLEM" is invalid. |
expired_certificate |
The certificate "EXPIRED" is expired. |
certificate_uses |
The certificate "8013DA6F" has no remaining uses for appointment type "1". |
invalid_certificate_type |
The certificate "E5E5325C" is invalid for appointment type "5". |
/appointments/:id
Get a single appointment by ID.
Canceled Appointments
Canceled appointments include a field, noShow which is true if the appointment was marked as a no-show by an admin and false if the appointment is simply canceled.
The scheduledBy field contains the username of the user or logged in client who scheduled the appointment. If an appointment was scheduled by a client not logged in, it will be null.
/appointments/:id
Update an appointment details from a white-list of updatable attributes.
Attributes not included in the request body or not on the white-list will be ignored. Appointments can be rescheduled and canceled with separate APIs.
firstNamelastNamephoneemailcertificatenotesfields
It is only necessary to send the attributes you would like to update, but required attributes such as firstName and lastName may not be cleared.
Updating Forms
Form data may be updated using the special fields attribute. The fields are an array of field ID and value objects, {"id": fieldId, "value": fieldValue}.
Field IDs can be found in the GET /forms API or by editing the form in Acuity and inspecting the fields by right clicking the field and choosing "Inspect".
Values for the multi-valued field checkboxlist should be submitted as a single comma-delimited string.
PUT "https://acuityscheduling.com/api/v1/appointments/1"
{
"fields": [
{
"id": 1,
"value": "My field value."
}
]
}admin=true
By default appointments are updated as if they are being edited by a client. Updating an appointment as an admin allows setting the "notes" and/or "certificate" field, disabling attribute validations. To book as an admin pass the query parameter admin=true.
PUT "https://acuityscheduling.com/api/v1/appointments/1?admin=true"
{
"notes": "These are my notes."
}/appointments/:id/cancel
Cancel an appointment.
Cancel an appointment using this endpoint. Once canceled, appointments will have a noShow attribute. This attribute may be updated, but it isn't possible to un-cancel the appointment.
Cancel as an Admin
?admin=true
By default appointments are canceled as a client. Canceling an appointment as an admin allows setting the "noShow" field and disables cancellation rules. To cancel as an admin pass the query parameter admin=true.
No Email
Skip sending the cancellation e-mail and SMS by canceling the appointment with the noEmail=true query parameter.
Errors
Validation errors return a 400 error response:
{
"status_code": 400,
"message": "Clients are not allowed to cancel.",
"error": "cancel_not_allowed"
}| Error | Message |
|---|---|
cancel_not_allowed |
Clients are not allowed to cancel. |
cancel_too_close |
Clients are not allowed to cancel this close to the time of the appointment. |
/appointments/:id/reschedule
Reschedule an appointment.
Reschedule an appointment to a different date or calendar. Or both!
To reschedule to an overlapping time, get availability using the ignoreAppointmentIDs[] argument for /availability/times with the current appointment's ID.
Reschedule as an Admin
admin=true
By default appointments are reschedule as if by a client. Rescheduling as an admin disables availability validations. To reschedule as an admin pass the query parameter admin=true.
No Email
Skip sending the rescheduling e-mail and SMS by rescheduling the appointment with the noEmail=true query parameter.
Errors
Availability errors return a 400 error response:
{
"status_code": 400,
"message": "Class series may not be rescheduled.",
"error": "reschedule_series"
}| Error | Message |
|---|---|
reschedule_not_allowed |
Clients are not allowed to reschedule. |
reschedule_too_close |
Clients are not allowed to reschedule this close to the time of the appointment. |
reschedule_series |
Class series may not be rescheduled. |
reschedule_canceled |
Canceled appointments may not be rescheduled. |
invalid_calendar |
The calendar "987654321" does not exist. |
required_datetime |
The parameter "datetime" is required. |
invalid_timezone |
Invalid timezone "Aint/No_Timezone". |
invalid_datetime |
The datetime "asdf" is invalid. |
not_available_min_hours_in_advance |
The time "2016-01-05T16:00:00-0800" is not far enough in advance. |
not_available_max_days_in_advance |
The time "2017-02-07T16:00:00" is too far in advance. |
not_available |
The time "2016-03-08T05:00:00-0800" is not an available time slot. |
/appointments/:id/payments
Retrieve a list of payment transactions for a particular appointment.
/appointment-addons
Get a full list of addons from the authenticated user.
Addons can add time and duration to an appointment before it is booked.
Click here to learn more about how to use add-ons via API in action.
/appointment-types
Return appointment types.
id
appointment type ID
name
the name of the appointment type
description
the description of the appointment type
duration
the duration in minutes
price
the price in the account's currency
category
the category of the appointment type
color
the color of the appointment type
private
whether or not the appointment type is a private type
type
the kind of appointment type: service, class or series (a series is a class which the client should book all times offered)
classSize
for a class or series the maximum class size, null otherwise
paddingAfter
the post-appointment padding in minutes
paddingBefore
the pre-appointment padding in minutes
calendarIDs
the IDs of calendars this type is offered on
/availability/dates
Return dates with availability for a month and an appointment type.
This endpoint returns an appointment type's available dates for a particular month. These dates are the same as those shown to the client through the client scheduling page.
Use /availability/dates together with /availability/times to find available slots for creating an appointment.
/availability/times
Return available times for a date and appointment type.
This endpoint returns an appointment type's available time slots for a particular date. These times are the same as those shown to the client through the client scheduling page.
Use /availability/times together with /availability/dates to find available slots for creating an appointment.
/availability/classes
Return available classes for a given month.
appointmentTypeID
the ID of the appointment type of the class offering
calendarID
the ID of the calendar the class is offered on
name
the name of the appointment type
time
the time of the class offering
calendar
the name of the calendar
duration
the duration of the class in minutes
isSeries
whether or not the class is a series (a series is a class which the client should book all times offered)
slots
the maximum number of attendees in the class
slotsAvailable
the remaining slots still available
Use /availability/classes to display class schedules, or for creating an appointment.
/availability/check-times
Validate available times for an appointment.
This endpoint available validates slots for an appointment. If a slot is valid and available, the response will include "valid": true. Otherwise, if a time is not a valid slot or not an available slot, "valid": false will be returned along with a reason.
Post an array to check multiple times at once:
POST "https://acuityscheduling.com/api/v1/availability/check-times"
[
{
"datetime": "2017-11-15T16:00:00-0800",
"appointmentTypeID": 1,
"calendarID": 1
},
{
"datetime": "2017-11-16T16:00:00-0800",
"appointmentTypeID": 1,
"calendarID": 1
}
]/blocks
POST request to block off time on your calendar.
Will return error 422 Unprocessable Entity if not able to parse data, or invalid parameter passed.
/blocks/:id
Given an ID of a blocked off time get the details about it.
Returns 200 on success. Returns 404 if not found.
/certificates
Create a package or coupon certificate.
Create certificate codes for packages, coupons, etc. in Acuity. Either productID (for packages) or couponID must be submitted. If you have one picked out (eg. "FOOBAR") you can submit the certificate parameter as well, otherwise we'll generate a random certificate for you.
Submitting the email parameter for a package assigns the certificate to that client email address.
/certificates/check
Check that a certificate code is valid for a particular appointment type.
Check that a certificate code is valid for a particular appointment type. Use this to validate a certificate code before setting it on an appointment.
Optionally check that the certificate code is still valid for a particular client e-mail address too, eg. in the case of single-use coupons.
/forms
Return intake forms.
id
form ID
name
the name of the form
description
the description of the form
hidden
whether or not the form is internal and hidden from clients
appointmentTypeIDs
the IDs of the appointment types the form is assigned to
fields
the list of form fields
Form Fields
Form fields are returned with the rest of the forms data. This list can be used to build a custom scheduler which supports intake forms, just be sure to implement each type of form field you're using!
id
the field ID
name
the field name
required
whether or not the field is required for clients
type
the field type, one of textbox, textarea, dropdown, checkbox, checkboxlist, yesno, file, or address
options
the list of options for dropdown and checkboxlist fields
/me
Get basic account information.
firstDayOfWeekset under Customize Appearance, the value is 0 or 1 (Sunday or Monday)timeFormatset under Customize Appearance, the value isampmor24h
/orders
Retrieves a list of orders from the online store with most recent first. Status can be delivered, paid, or unpaid. Title is a semi-colon separated list of the product names ordered.
/products
Get a list of products and packages.
id
The product ID.
name
The name of the product.
description
The description of the product.
price
The price of the product in the account's currency.
type
The product type: product for regular products, appointments for packages of appointments, or minutes for packages of minutes.
hidden
Whether or not the product is hidden from the store.
expires
The number of days from the date of purchase that a package expires. Null if it does not expire.
appointmentTypeIDs
The appointment types that a package can be applied to.
appointmentTypeCounts
A hash containing the total number of appointments an appointments package may be redeemed for, keyed by appointment type ID; null otherwise.
minutes
The total number of minutes of the selected appointment types a minutes package may be redeemed for; null otherwise.
API Errors
Here's what can go wrong in Acuity's API, and how to fix it. As always, feel free to reach out to developers@acuityscheduling.com if you run into a problem you're having trouble fixing!
General API Errors
These are the errors we all know and love. They're errors that can happen in most web applications, and they should be straight forward to solve.
| Status | Error | Response | Description |
|---|---|---|---|
| 400 | Bad Request | {"status_code": 400, "message": "Expected a JSON object.", "error": "bad_request"} |
The request requires a JSON body, but we couldn't parse it. Double check that you're sending a request body and that the body is valid JSON. |
| 401 | Unauthorized | {"status_code": 401, "message": "Unauthorized", "error": "unauthorized" } |
We don't know who you are! Either the request didn't include authentication or the authentication wasn't valid. Double check the user ID and API key, or head to Getting Started for an example. |
| 403 | Forbidden | { "status_code": 403, "message": "Forbidden", "error": "forbidden" } |
The request included authentication and we know who you are, but you don't have access to the resource. Eg. the calendar or appointment type belongs to another user. |
| 404 | Not Found | { "status_code": 404, "message": "Not Found. Did you mean `/appointments/{id:number}`?", "error": "not_found" } |
The requested resource could not be found. Fat fingers happen, so if it looks like a typo we'll do our best to suggest the correct endpoint. Also double check URI IDs, in case the resource legitimately does not exist. |
| 405 | Method Not Allowed | { "status_code": 405, "message": "Method Not Allowed", "error": "method_not_allowed" } |
The resource exists but the HTTP method is not supported. Not all of our endpoints support the same methods. Check our docs for the methods which are supported. |
| 429 | Too Many Requests | {"status_code": 429,"error": "too_many_requests","message": "Rate limit reached. Limit 10req/s and 20 concurrent connections."} |
Woah there! Our API is currently rate limited to 10 requests a second and 20 concurrent connections from an IP. |
| 500 | Internal Server Error | { "status_code": 500, "message": "Internal Server Error", "error":"internal_server_error" } |
Something unexpected happened. These errors should not happen, but when they do we'll get notified and be on the case quickly. Feel free to reach out to us at developers@acuityscheduling.com. |
Specific API Errors
Many of our endpoints return specific errors related to that endpoint. These errors will will do their best to include a descriptive message about what went wrong. The error response body looks like this:
{
"status_code": 400,
"error": "invalid_name",
"message": "Can not clear the field \"firstName\"."
}| Status | Error | Response | Description |
|---|---|---|---|
| 400 | Bad Request | {"status_code": 400, "message": "Can not clear the field \"firstName\".", "error": "invalid_name"} |
General validation errors such as unexpected values or missing required fields will generate 400 errors. We'll give a descriptive message about what went wrong to help you resolve it. |
| 422 | Unprocessable Entity | {"status_code": 422, "message": "End is before start.", "error": "invalid_time"} |
Left over from before RFC 7231 opened up the description of the 400 status code, our POST /blocks endpoint returns 422 error on time validation errors. |
Attributed to Rogério Vicente & Tonomi - https://http.cat/