--- updatedAt: 2025-06-09T23:19:46.000Z agentTools: projectIndex: https://developers.acuityscheduling.com/llms.txt --- # /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](https://developers.acuityscheduling.com/docs/get-availability-dates) and [/availability/times](https://developers.acuityscheduling.com/docs/get-availability-times) or [/availability/classes](https://developers.acuityscheduling.com/docs/get-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 valid`calendarID`to be included in the request. ```json Example Admin 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](https://developers.acuityscheduling.com/reference/forms) or by [editing the form in Acuity](https://secure.acuityscheduling.com/forms.php) 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. ```json Example Request with Forms 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](https://developers.acuityscheduling.com/docs/get-certificates-check). Try out the [/certificates endpoint](https://developers.acuityscheduling.com/docs/get-certificates) to suggest certificates for a particular client. ### Addons [Addons ](https://help.acuityscheduling.com/hc/en-us/articles/218724718-Add-ons-Adding-On-Extra-Services-Time-to-Appointments) can add time and duration to an appointment before it is booked. Use [/appointments-addons](https://developers.acuityscheduling.com/reference/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](https://developers.acuityscheduling.com/v1.1/page/appointment-addons). ### 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: ```json 400 { "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". | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "v1", "version": "1.1" }, "servers": [ { "url": "https://acuityscheduling.com/api/v1" } ], "components": { "securitySchemes": { "sec0": { "type": "http", "scheme": "basic" } } }, "security": [ { "sec0": [] } ], "paths": { "/appointments": { "post": { "summary": "/appointments", "description": "Create an appointment.", "operationId": "post-appointments", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "datetime", "appointmentTypeID", "firstName", "lastName", "email" ], "properties": { "datetime": { "type": "string", "description": "Required date and time for the appointment, parsed by strtotime in the business or calendar timezone. (http://php.net/manual/en/function.strtotime.php)" }, "appointmentTypeID": { "type": "integer", "description": "Appointment type id.", "format": "int32" }, "calendarID": { "type": "integer", "description": "Calendar ID. If not provided we'll try to find an available calendar automatically.", "format": "int32" }, "firstName": { "type": "string", "description": "Client first name." }, "lastName": { "type": "string", "description": "Client last name." }, "email": { "type": "string", "description": "Client e-mail address. Optional for admins." }, "phone": { "type": "string", "description": "Client phone number, may be required in account settings. Optional for admins." }, "timezone": { "type": "string", "description": "Client timezone." }, "certificate": { "type": "string", "description": "Package or coupon certificate code." }, "fields": { "type": "array", "description": "A special field for setting form field values.", "items": { "properties": { "label": { "type": "string", "description": "An array of label objects. Currently only accepts an array of length 1" } }, "type": "object" } }, "notes": { "type": "string", "description": "Settable when [booking as an admin](https://developers.acuityscheduling.com/v1.1/reference#section-booking-as-an-admin)." }, "addonIDs": { "type": "integer", "description": "ID of the addon(s) to be included in the scheduled appointment", "format": "int32" }, "labels": { "type": "array", "description": "An array of label objects. Currently only accepts an array of length 1." }, "smsOptIn": { "type": "boolean", "description": "Indicates whether the client has explicitly given their permission to receive SMS messages. This parameter is only applicable to Appointments with an Appointment Type that requires Opt In and can be omitted (and will be ignored) for all other Appointments. If omitted or set to false on an applicable Appointment, an SMS reminder will not be sent. For more information on SMS Opt In settings for Appointment Types, see the article in our [Knowledge Base](https://support.squarespace.com/hc/en-us/articles/360040093611).", "default": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"id\": 31991639,\n \"firstName\": \"Bob\",\n \"lastName\": \"McTest\",\n \"phone\": \"\",\n \"email\": \"bob.mctest@example.com\",\n \"date\": \"February 3, 2016\",\n \"time\": \"2:00pm\",\n \"endTime\": \"3:00pm\",\n \"dateCreated\": \"February 2, 2016\",\n \"datetime\": \"2016-02-03T14:00:00-0800\",\n \"price\": \"0.00\",\n \"paid\": \"no\",\n \"amountPaid\": \"0.00\",\n \"type\": \"Regular Visit\",\n \"appointmentTypeID\": 1,\n \"classID\": null,\n \"category\": \"\",\n \"duration\": \"60\",\n \"calendar\": \"My Calendar\",\n \"calendarID\": 1,\n \"location\": \"\",\n \"certificate\": \"ABC123\",\n \"confirmationPage\": \"https://www.acuityscheduling.com/schedule.php?action=appt&owner=11145481&id[]=1220aa9f41091c50c0cc659385cfa1d0\",\n \"formsText\": \"...\",\n \"forms\": [],\n \"notes\": \"\",\n \"timezone\": \"America/Los_Angeles\",\n \"labels\": [\n {\n \"id\": 1,\n \"name\": \"Completed\",\n \"color\": \"pink\"\n }\n ]\n ]\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"status_code\": 400,\n \"message\": \"We could not find an available calendar.\",\n \"error\": \"no_available_calendar\"\n}" } }, "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 400, "default": 0 }, "message": { "type": "string", "example": "We could not find an available calendar." }, "error": { "type": "string", "example": "no_available_calendar" } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "javascript", "code": "var Acuity = require('acuityscheduling');\n\nvar acuity = Acuity.basic({\n userId: ACUITY_USER_ID,\n apiKey: 'ACUITY_API_KEY'\n});\n\n// Create appontment options:\nvar options = {\n method: 'POST',\n body: {\n appointmentTypeID : 1,\n datetime : '2016-04-01T09:00',\n firstName : 'Bob',\n lastName : 'McTest',\n email : 'bob.mctest@example.com'\n }\n};\n\n// Make the create appointment request:\nacuity.request('/appointments', options, function (err, res, appointment) {\n if (err) return console.error(err);\n console.log(appointment);\n});", "name": "js-sdk" }, { "language": "php", "code": " ACUITY_USER_ID,\n 'apiKey' => 'ACUITY_API_KEY'\n));\n// Make the create-appointment request:\n$appointment = $acuity->request('/appointments', array(\n 'method' => 'POST',\n 'data' => array(\n 'appointmentTypeID' => 274497,\n 'datetime' => '2016-04-01T09:00',\n 'firstName' => 'Bob',\n 'lastName' => 'McTest',\n 'email' => 'bob.mctest@example.com'\n )\n));\nprint_r($appointment);", "name": "php-sdk" } ], "samples-languages": [ "javascript", "php" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```