openapi: 3.0.3
info:
  title: Acuity Scheduling Appointments API
  description: 'The Acuity Scheduling REST API allows developers to programmatically manage appointments, appointment types, availability, client records, calendar integrations, packages, gift certificates, and forms. Authentication is supported via HTTP Basic Auth using a User ID and API Key, or via OAuth2 for multi-account integrations. All responses are JSON. Webhooks allow receiving real-time push notifications for appointment lifecycle events.

    '
  version: '1.1'
  contact:
    url: https://developers.acuityscheduling.com/
  x-provider: Acuity Scheduling
  x-subsidiary: Squarespace
servers:
- url: https://acuityscheduling.com/api/v1
  description: Acuity Scheduling API v1
security:
- basicAuth: []
tags:
- name: Appointments
paths:
  /appointments:
    get:
      summary: List appointments
      description: Get a list of appointments currently scheduled for the authenticated user.
      operationId: get-appointments
      tags:
      - 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 (include noShow field in response)
        schema:
          type: boolean
          default: false
      - name: showall
        in: query
        description: Retrieve both canceled and scheduled 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
        schema:
          type: string
      - name: field:id
        in: query
        description: Filter appointments matching a particular custom intake form field e.g. ?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: Sort direction
        schema:
          type: string
          default: DESC
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: List of appointments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Appointment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
    post:
      summary: Create an appointment
      description: 'Create an appointment. By default, availability and forms are validated as if the appointment is being booked by a client. Use admin=true to disable availability and attribute validations and to allow setting notes.

        '
      operationId: post-appointments
      tags:
      - Appointments
      parameters:
      - name: admin
        in: query
        description: Book as admin — disables availability and attribute validations, allows setting notes. Requires a valid calendarID in the request body.
        schema:
          type: boolean
          default: false
      - name: noEmail
        in: query
        description: Don't send confirmation e-mails or SMS
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        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.
                  example: 2016-02-03T14:00:00-0800
                appointmentTypeID:
                  type: integer
                  format: int32
                  description: Appointment type ID
                  example: 1
                calendarID:
                  type: integer
                  format: int32
                  description: Calendar ID. If not provided, an available calendar will be found automatically.
                firstName:
                  type: string
                  description: Client first name
                  example: Bob
                lastName:
                  type: string
                  description: Client last name
                  example: McTest
                email:
                  type: string
                  description: Client e-mail address. Optional for admins.
                  example: bob.mctest@example.com
                phone:
                  type: string
                  description: Client phone number. May be required in account settings. Optional for admins.
                timezone:
                  type: string
                  description: Client timezone
                  example: America/New_York
                certificate:
                  type: string
                  description: Package or coupon certificate code
                fields:
                  type: array
                  description: A special field for setting form field values
                  items:
                    $ref: '#/components/schemas/FormField'
                notes:
                  type: string
                  description: Settable only when booking as an admin
                addonIDs:
                  type: array
                  description: IDs of addons to be included in the scheduled appointment
                  items:
                    type: integer
                    format: int32
                labels:
                  type: array
                  description: An array of label objects. Currently only accepts an array of length 1.
                  items:
                    $ref: '#/components/schemas/Label'
                smsOptIn:
                  type: boolean
                  description: Whether the client has explicitly given permission to receive SMS messages. Only applicable when the appointment type requires opt-in.
                  default: false
      responses:
        '200':
          description: Created appointment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '400':
          description: Validation or availability error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /appointments/{id}:
    put:
      summary: Update an appointment
      description: 'Update appointment details from a whitelist of updatable attributes. Attributes not included in the request body or not on the whitelist will be ignored. Appointments can be rescheduled and canceled with separate APIs.

        '
      operationId: put-appointments-id
      tags:
      - Appointments
      parameters:
      - name: id
        in: path
        description: Appointment ID
        required: true
        schema:
          type: integer
          format: int32
      - name: admin
        in: query
        description: Update as admin — allows setting notes and certificate, disables attribute validations.
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: Client first name; may not be removed
                lastName:
                  type: string
                  description: Client last name; may not be removed
                email:
                  type: string
                  description: Client email. May not be removed for clients; optional for admins.
                phone:
                  type: string
                  description: Client phone. May not be removed for clients depending on account settings; optional for admins.
                certificate:
                  type: string
                  description: Package or coupon certificate code. May only be set by admins.
                fields:
                  type: array
                  description: A special field for updating form field values
                  items:
                    $ref: '#/components/schemas/FormField'
                notes:
                  type: string
                  description: May only be set by admins.
                labels:
                  type: array
                  description: An array of label objects. Currently only accepts an array of length 1.
                  items:
                    $ref: '#/components/schemas/Label'
                smsOptIn:
                  type: boolean
                  description: Whether the client has explicitly given permission to receive SMS messages. Omit to leave unchanged.
                  default: false
      responses:
        '200':
          description: Updated appointment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /appointments/{id}/payments:
    get:
      summary: Get appointment payments
      description: Retrieve a list of payment transactions for a particular appointment.
      operationId: get-appointments-id-payments
      tags:
      - Appointments
      parameters:
      - name: id
        in: path
        description: Appointment ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List of payment transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  schemas:
    AppointmentForm:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        name:
          type: string
          example: Example Intake Form
        values:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                example: 'yes'
              name:
                type: string
                example: Is this your first visit?
              fieldID:
                type: integer
                format: int32
                example: 1
              id:
                type: integer
                format: int32
                example: 21502993
    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
          example: 400
        message:
          type: string
          example: We could not find an available calendar.
        error:
          type: string
          example: no_available_calendar
    Appointment:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 54321
        firstName:
          type: string
          example: Bob
        lastName:
          type: string
          example: McTest
        phone:
          type: string
          example: ''
        email:
          type: string
          example: bob.mctest@example.com
        date:
          type: string
          example: July 2, 2013
        time:
          type: string
          example: 10:15am
        endTime:
          type: string
          example: 11:15am
        dateCreated:
          type: string
          example: June 17, 2013
        datetime:
          type: string
          format: date-time
          example: 2013-07-02T10:15:00-0700
        price:
          type: string
          example: '10.00'
        paid:
          type: string
          example: 'no'
        amountPaid:
          type: string
          example: '0.00'
        type:
          type: string
          example: Regular Visit
        appointmentTypeID:
          type: integer
          format: int32
          example: 1
        addonIDs:
          type: array
          items:
            type: integer
            format: int32
        classID:
          type: integer
          format: int32
          nullable: true
        category:
          type: string
          example: ''
        duration:
          type: string
          example: '60'
        calendar:
          type: string
          example: My Calendar
        calendarID:
          type: integer
          format: int32
          example: 27238
        canClientCancel:
          type: boolean
          example: false
        canClientReschedule:
          type: boolean
          example: false
        location:
          type: string
          example: ''
        certificate:
          type: string
          nullable: true
        confirmationPage:
          type: string
          example: https://acuityscheduling.com/schedule.php?owner=11145481&id[]=1220aa9f41091c50c0cc659385cfa1d0&action=appt
        formsText:
          type: string
          example: '...'
        notes:
          type: string
          example: Notes
        noShow:
          type: boolean
          description: True if admin has marked the canceled appointment as a no-show
        timezone:
          type: string
          example: America/New_York
        forms:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentForm'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    Payment:
      type: object
      properties:
        transactionID:
          type: string
          example: pi_123456abcdef
          description: The 3rd-party processor transaction ID
        created:
          type: string
          format: date-time
          example: 2016-01-22T09:27:51-0800
          description: Date the transaction was created
        processor:
          type: string
          example: stripe
          description: 'Payment processor key: stripe, paypal, paypal_pro, braintree, or authorizenet'
          enum:
          - stripe
          - paypal
          - paypal_pro
          - braintree
          - authorizenet
        amount:
          type: string
          example: '300.00'
          description: Amount of the processed transaction
    Label:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 3
        name:
          type: string
          example: Completed
        color:
          type: string
          example: pink
    UnauthorizedError:
      type: object
      properties:
        status_code:
          type: integer
          example: 401
        message:
          type: string
          example: Unauthorized
        error:
          type: string
          example: unauthorized
    FormField:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Form field ID
        value:
          type: string
          description: Field value; use comma-delimited string for checkboxlist fields
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using Acuity User ID and API Key
    oauth2:
      type: oauth2
      description: OAuth2 for multi-account integrations
      flows:
        authorizationCode:
          authorizationUrl: https://acuityscheduling.com/oauth2/authorize
          tokenUrl: https://acuityscheduling.com/oauth2/token
          scopes:
            api: Full API access