--- updatedAt: 2025-06-09T23:19:44.000Z agentTools: projectIndex: https://developers.acuityscheduling.com/llms.txt --- # /appointments Get a list of appointments currently scheduled for the authenticated user. ### Canceled Appointments > 📘 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. # 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": { "get": { "summary": "/appointments", "description": "Get a list of appointments currently scheduled for the authenticated user.", "operationId": "get-appointments", "parameters": [ { "name": "max", "in": "query", "description": "maximum number of results", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "minDate", "in": "query", "description": "only get appointments this date and after", "schema": { "type": "string", "format": "date" } }, { "name": "maxDate", "in": "query", "description": "only get appointments this date and before", "schema": { "type": "string", "format": "date" } }, { "name": "calendarID", "in": "query", "description": "show only appointments on calendar with specified ID", "schema": { "type": "integer", "format": "int32" } }, { "name": "appointmentTypeID", "in": "query", "description": "show only appointments of this type", "schema": { "type": "integer", "format": "int32" } }, { "name": "canceled", "in": "query", "description": "get canceled appointments", "schema": { "type": "boolean", "default": false } }, { "name": "firstName", "in": "query", "description": "filter appointments for client first name", "schema": { "type": "string" } }, { "name": "lastName", "in": "query", "description": "filter appointments for client last name", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "filter appointments for client e-mail address", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "description": "filter appointments for client phone number. If using a country code, ensure that the '+' is URL encoded to %2b for accurate results", "schema": { "type": "string" } }, { "name": "field:id", "in": "query", "description": "filter appointments matching a particular custom intake form field eg. `?field:1234=Hello`", "schema": { "type": "string" } }, { "name": "excludeForms", "in": "query", "description": "don't include intake forms in the response object (speeds up the response)", "schema": { "type": "boolean", "default": false } }, { "name": "direction", "in": "query", "description": "ASC or DESC", "schema": { "type": "string", "default": "DESC" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "[{\n\t\"id\": 54321,\n\t\"firstName\": \"Bob\",\n\t\"lastName\": \"McTest\",\n\t\"phone\": \"\",\n\t\"email\": \"bob.mctest@example.com\",\n\t\"date\": \"July 2, 2013\",\n\t\"time\": \"10:15am\",\n\t\"endTime\": \"11:15am\",\n \"dateCreated\": \"June 17, 2013\",\n \"datetime\": \"2013-07-02T10:15:00-0700\",\n\t\"price\": \"10.00\",\n\t\"paid\": \"no\",\n \"amountPaid\": \"0.00\",\n\t\"type\": \"Regular Visit\",\n \"appointmentTypeID\": 1,\n \"addonIDs\": [\n 1\n ],\n \"classID\": null,\n\t\"duration\": \"60\",\n\t\"calendar\": \"My Calendar\",\n\t\"calendarID\": 27238,\n \"canClientCancel\": false,\n \"canClientReschedule\": false,\n \"location\": \"\",\n \"certificate\": null,\n\t\"confirmationPage\": \"https://acuityscheduling.com/schedule.php?owner=11145481&id[]=1220aa9f41091c50c0cc659385cfa1d0&action=appt\",\n\t\"formsText\": \"...\",\n\t\"notes\": \"Notes\",\n\t\"timezone\": \"America/New_York\",\n\t\"forms\": [\n\t\t{\n\t\t\t\"id\": 1,\n\t\t\t\"name\": \"Example Intake Form\",\n\t\t\t\"values\": [\n\t\t\t\t{\n\t\t\t\t\t\"value\": \"yes\",\n\t\t\t\t\t\"name\": \"Is this your first visit?\",\n\t\t\t\t\t\"fieldID\": 1,\n\t\t\t\t\t\"id\": 21502993\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"value\": \"Ninja\",\n\t\t\t\t\t\"name\": \"What is your goal for this appointment?\",\n\t\t\t\t\t\"fieldID\": 2,\n\t\t\t\t\t\"id\": 21502994\n\t\t\t\t}\n\t\t\t]\n\t\t},\n\t],\n \"labels\": [\n {\n \t\t\"id\": 3,\n \"name\": \"Completed\",\n \"color\": \"pink\"\n }\n ]\n},\n{\n\t\"id\": 2051308,\n\t\"firstName\": \"Eve\",\n\t\"lastName\": \"Cooper\",\n\t\"phone\": \"1231231234\",\n\t\"email\": \"eve@example.com\",\n\t\"date\": \"June 24, 2013\",\n \"datetime\": \"2013-06-24T09:00:00-0700\",\n\t\"time\": \" 9:00am\",\n\t\"endTime\": \"10:00am\",\n\t\"price\": \"0.00\",\n\t\"paid\": \"no\",\n\t\"type\": \"Another Type\",\n \"appointmentTypeID\": 2,\n \"addonIDs\": [],\n \"classID\": 1,\n\t\"duration\": \"60\",\n\t\"calendar\": \"My Calendar\",\n\t\"calendarID\": 27238,\n \"canClientCancel\": false,\n \"canClientReschedule\": false,\n \"location\": \"\",\n\t\"confirmationPage\": \"https://acuityscheduling.com/schedule.php?owner=11145481&id[]=3320aa9f41091c50c0cc659385cfa1d0&action=appt\",\n\t\"formsText\": \"...\",\n\t\"notes\": \"Notes\",\n\t\"timezone\": \"America/New_York\",\n\t\"forms\": [],\n \"labels\": []\n}]" } } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Result": { "value": "{\"status_code\": 401, \"message\": \"Unauthorized\", \"error\": \"unauthorized\"}" } }, "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 401, "default": 0 }, "message": { "type": "string", "example": "Unauthorized" }, "error": { "type": "string", "example": "unauthorized" } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -u ACUITY_USER_ID:ACUITY_API_KEY \"https://acuityscheduling.com/api/v1/appointments?max=25&calendarID=27238\"" } ], "samples-languages": [ "shell" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```