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": "[email protected]",
  "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 }
]

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.

ErrorMessage
required_first_nameAttribute "firstName" is required.
required_last_nameAttribute "lastName" is required.
required_emailAttribute "email" is required.
invalid_emailInvalid "email" attribute value.
invalid_fieldsThe field "1" does not exist on this appointment.
required_fieldThe field "4" is required.
required_appointment_type_idThe parameter "appointmentTypeID" is required.
invalid_appointment_typeThe appointment type "987654321" does not exist.
invalid_calendarThe calendar "987654321" does not exist.
required_datetimeThe parameter "datetime" is required.
invalid_timezoneInvalid timezone "Aint/No_Timezone".
invalid_datetimeThe datetime "asdf" is invalid.
no_available_calendarWe could not find an available calendar.
not_available_min_hours_in_advanceThe time "2016-01-05T16:00:00-0800" is not far enough in advance.
not_available_max_days_in_advanceThe time "2017-02-07T16:00:00" is too far in advance.
not_availableThe time "2016-03-08T05:00:00-0800" is not an available time slot.
invalid_certificateThe certificate "NOCODENOPROBLEM" is invalid.
expired_certificateThe certificate "EXPIRED" is expired.
certificate_usesThe certificate "8013DA6F" has no remaining uses for appointment type "1".
invalid_certificate_typeThe certificate "E5E5325C" is invalid for appointment type "5".
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!