Vagaro Appointments API

openapi: 3.0.3
info:
  title: Vagaro Enterprise Business API (Partial, Community-Modeled)
  description: >-
    Vagaro publishes a "PUBLIC - Enterprise Business API V2" reference at
    docs.vagaro.com (readme.io). The Access Token endpoint below is transcribed
    directly from that public reference page: method, full path pattern,
    request body fields, and documented response codes. The Appointments,
    Customers, Employees, Employee Management, and Locations paths are
    honestly modeled from Vagaro's own capability-level descriptions of those
    five areas ("retrieve details about appointments including status, start
    time, and service provider", "obtain customer contact information and
    tags", "view service provider details, contact information, and reporting
    relationships", "assign and unassign employees across locations with
    access levels, provision/deprovision calendars", "retrieve single or
    multi-location business details") and from the confirmed field names in
    Vagaro's Webhook event payloads (Appointment, Customer, Employee, Business
    Location events). Exact parameter names, pagination style, and full
    response schemas for those five areas are not publicly visible without an
    approved Vagaro partner account and are marked x-endpointsModeled: true.
    Do not treat the modeled paths as verified against a live response.
  version: v2
  contact:
    name: Vagaro
    url: https://www.vagaro.com/pro
  license:
    name: Proprietary
    url: https://docs.vagaro.com/
servers:
  - url: https://api.vagaro.com/{region}/api/v2
    description: Vagaro Enterprise Business API (region-scoped)
    variables:
      region:
        default: us
        description: Business region assigned to the Vagaro account, as documented in the API basics guide.
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Access token issuance for the Enterprise Business API.
  - name: Appointments
    description: Appointment status, timing, and service-provider details. Endpoints modeled.
  - name: Customers
    description: Customer contact information and tags. Endpoints modeled.
  - name: Employees
    description: Service provider contact information and reporting relationships. Endpoints modeled.
  - name: Employee Management
    description: Assign/unassign staff across locations and provision calendars. Endpoints modeled.
  - name: Locations
    description: Single- and multi-location business details. Endpoints modeled.
paths:
  /merchants/generate-access-token:
    post:
      operationId: generateAccessToken
      tags:
        - Authentication
      summary: Generate an access token
      description: >-
        Exchanges a partner clientId and clientSecretKey, plus a comma-
        separated list of requested scopes, for a bearer access token. This
        endpoint, its method, and its path are transcribed from Vagaro's
        public reference page and are not modeled.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized - invalid clientId/clientSecretKey.
        '429':
          description: Too many requests.
  /appointments:
    get:
      operationId: listAppointments
      tags:
        - Appointments
      summary: List appointments (modeled)
      description: >-
        Modeled from Vagaro's documented capability summary and the confirmed
        Appointment webhook payload fields. Exact query parameters and
        pagination are not publicly confirmed.
      x-endpointsModeled: true
      parameters:
        - name: businessId
          in: query
          schema:
            type: string
          description: Modeled - filter to a single business location.
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          description: Modeled - inclusive range start.
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          description: Modeled - inclusive range end.
      responses:
        '200':
          description: A list of appointments (modeled response shape).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments/{appointmentId}:
    get:
      operationId: getAppointment
      tags:
        - Appointments
      summary: Get an appointment (modeled)
      x-endpointsModeled: true
      parameters:
        - name: appointmentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An appointment (modeled response shape).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Appointment not found.
  /customers:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers (modeled)
      description: >-
        Modeled from Vagaro's documented capability summary and the confirmed
        Customer webhook payload fields.
      x-endpointsModeled: true
      parameters:
        - name: businessId
          in: query
          schema:
            type: string
          description: Modeled - filter to a single business location.
      responses:
        '200':
          description: A list of customers (modeled response shape).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}:
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Get a customer (modeled)
      x-endpointsModeled: true
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A customer (modeled response shape).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Customer not found.
  /employees:
    get:
      operationId: listEmployees
      tags:
        - Employees
      summary: List employees / service providers (modeled)
      description: >-
        Modeled from Vagaro's documented capability summary and the confirmed
        Employee webhook payload fields.
      x-endpointsModeled: true
      parameters:
        - name: businessId
          in: query
          schema:
            type: string
          description: Modeled - filter to a single business location.
      responses:
        '200':
          description: A list of employees (modeled response shape).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}:
    get:
      operationId: getEmployee
      tags:
        - Employees
      summary: Get an employee (modeled)
      x-endpointsModeled: true
      parameters:
        - name: employeeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An employee (modeled response shape).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Employee not found.
  /employees/{employeeId}/locations/{businessId}/assignment:
    put:
      operationId: assignEmployeeToLocation
      tags:
        - Employee Management
      summary: Assign an employee to a location with an access level (modeled)
      description: >-
        Modeled from Vagaro's documented capability summary: "easily manage
        employees across multiple locations by assigning and unassigning them
        while specifying what access level they should have".
      x-endpointsModeled: true
      parameters:
        - name: employeeId
          in: path
          required: true
          schema:
            type: string
        - name: businessId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accessLevel:
                  type: string
                  description: Modeled - e.g. Owner, Manager, Front Desk, Service Provider.
                provisionCalendar:
                  type: boolean
                  description: Modeled - provision a bookable calendar for the employee at this location.
      responses:
        '200':
          description: Assignment applied (modeled response shape).
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: unassignEmployeeFromLocation
      tags:
        - Employee Management
      summary: Unassign an employee from a location (modeled)
      x-endpointsModeled: true
      parameters:
        - name: employeeId
          in: path
          required: true
          schema:
            type: string
        - name: businessId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Unassignment applied (modeled response shape).
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations:
    get:
      operationId: listLocations
      tags:
        - Locations
      summary: List business locations (modeled)
      description: >-
        Modeled from Vagaro's documented capability summary and the confirmed
        Business Location webhook payload fields.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of business locations (modeled response shape).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations/{businessId}:
    get:
      operationId: getLocation
      tags:
        - Locations
      summary: Get a business location (modeled)
      x-endpointsModeled: true
      parameters:
        - name: businessId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A business location (modeled response shape).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Location not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token issued by /merchants/generate-access-token
  responses:
    Unauthorized:
      description: Missing or invalid access token, or token lacks the required scope.
  schemas:
    AccessTokenRequest:
      type: object
      required:
        - clientId
        - clientSecretKey
        - scope
      properties:
        clientId:
          type: string
          description: Unique client identifier issued when APIs & Webhooks access is approved.
        clientSecretKey:
          type: string
          description: Unique client secret issued alongside clientId.
        scope:
          type: string
          description: Comma-separated list of scopes; the required scope is listed on each API reference page.
    AccessTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
        tokenType:
          type: string
          example: Bearer
        expiresIn:
          type: integer
          description: Modeled - token lifetime in seconds; exact value not publicly confirmed.
        scope:
          type: string
    Appointment:
      type: object
      description: Fields confirmed via the Appointment webhook payload documentation.
      properties:
        appointmentId:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        bookingStatus:
          type: string
          description: e.g. Confirmed, Awaiting Confirmation, No Show, Service Completed.
        serviceTitle:
          type: string
        serviceId:
          type: string
        amount:
          type: number
        eventType:
          type: string
          description: Appointment, Class, or PersonalOff.
        customerId:
          type: string
        serviceProviderId:
          type: string
        businessId:
          type: string
        bookingSource:
          type: string
          description: e.g. Google, Yelp, Instagram, Facebook, Vagaro Marketplace.
        formResponseIds:
          type: array
          items:
            type: string
    Customer:
      type: object
      description: Modeled from the documented capability ("contact information and tags") and Customer webhook events.
      properties:
        customerId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        tags:
          type: array
          items:
            type: string
        businessId:
          type: string
    Employee:
      type: object
      description: Modeled from the documented capability ("contact information and reporting structure") and Employee webhook events.
      properties:
        employeeId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        title:
          type: string
        reportsToEmployeeId:
          type: string
        businessId:
          type: string
    Location:
      type: object
      description: Modeled from the documented capability ("single or multi-location business details") and Business Location webhook events.
      properties:
        businessId:
          type: string
        businessName:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
        timeZone:
          type: string