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. This also requires a validcalendarIDto be included in the request.

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. Make sure to include a space after each comma in the 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.

Labels

The API currently on accepts one label per appointment, although it is passed by an array.

"labels":[
{ "id": 1 }
][
{ "id": 1 }
]

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".