openapi: 3.0.3
info:
  title: IntakeQ API
  description: >-
    The IntakeQ API is a documented REST API for the IntakeQ / PracticeQ practice
    management platform used by health and wellness practitioners. It exposes
    clients, appointments, intake questionnaires and consent forms, treatment
    notes, invoices, and file attachments. All endpoints live under
    https://intakeq.com/api/v1 and every request must carry the account's API key
    in an `X-Auth-Key` header (found under More > Settings > Integrations >
    Developer API). Several resources also emit webhooks (intake completed,
    note locked, invoice events) configured in the API settings; those are
    server-to-endpoint HTTP callbacks and are not modeled as request/response
    operations here.
  version: '1.0'
  contact:
    name: IntakeQ
    url: https://intakeq.com
servers:
  - url: https://intakeq.com/api/v1
    description: IntakeQ production API
security:
  - authKey: []
tags:
  - name: Clients
    description: Clients (patients), tags, and diagnoses.
  - name: Appointments
    description: Appointments, booking settings, and cancellation.
  - name: Intake Forms
    description: Intake questionnaires, consent forms, templates, and practitioners.
  - name: Treatment Notes
    description: Treatment / clinical notes and PDF export.
  - name: Invoices
    description: Invoice query and retrieval.
  - name: Files
    description: Client file attachments and folders.
paths:
  /clients:
    get:
      operationId: queryClients
      tags:
        - Clients
      summary: Query clients
      description: >-
        Returns a list of clients. Filter with the query parameters below.
        Returns a maximum of 100 records per page.
      parameters:
        - name: search
          in: query
          description: Name, email, or numeric client ID to search for.
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination (max 100 records per page).
          schema:
            type: integer
        - name: includeProfile
          in: query
          description: Set to 'true' to include the full client profile.
          schema:
            type: boolean
        - name: dateCreatedStart
          in: query
          schema:
            type: string
            format: date
        - name: dateCreatedEnd
          in: query
          schema:
            type: string
            format: date
        - name: dateUpdatedStart
          in: query
          schema:
            type: string
            format: date
        - name: dateUpdatedEnd
          in: query
          schema:
            type: string
            format: date
        - name: externalClientId
          in: query
          description: Search by external client ID.
          schema:
            type: string
        - name: deletedOnly
          in: query
          description: Return only deleted clients (retrievable within 10 days of deletion).
          schema:
            type: boolean
      responses:
        '200':
          description: A list of clients.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: saveClient
      tags:
        - Clients
      summary: Save or update a client
      description: >-
        Creates a new client or updates an existing one. Include `ClientId` in
        the body to update an existing client; omit it to create a new client.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
      responses:
        '200':
          description: The saved client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /clientTags:
    post:
      operationId: addClientTag
      tags:
        - Clients
      summary: Add a tag to a client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ClientId
                - Tag
              properties:
                ClientId:
                  type: integer
                Tag:
                  type: string
      responses:
        '200':
          description: Tag added.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeClientTag
      tags:
        - Clients
      summary: Remove a tag from a client
      parameters:
        - name: clientId
          in: query
          required: true
          schema:
            type: integer
        - name: tag
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tag removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /client/{clientId}/diagnoses:
    get:
      operationId: queryClientDiagnoses
      tags:
        - Clients
      summary: Query a client's diagnoses
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A list of diagnoses for the client.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments:
    get:
      operationId: queryAppointments
      tags:
        - Appointments
      summary: Query appointments
      parameters:
        - name: client
          in: query
          description: Client name, email, or ID to filter by.
          schema:
            type: string
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: status
          in: query
          schema:
            type: string
        - name: practitionerEmail
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: updatedSince
          in: query
          schema:
            type: string
            format: date
        - name: deletedOnly
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: A list of appointments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createAppointment
      tags:
        - Appointments
      summary: Create an appointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentCreate'
      responses:
        '200':
          description: The created appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateAppointment
      tags:
        - Appointments
      summary: Update an appointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentUpdate'
      responses:
        '200':
          description: The updated appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments/{appointmentId}:
    get:
      operationId: getAppointment
      tags:
        - Appointments
      summary: Retrieve a single appointment
      parameters:
        - name: appointmentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments/settings:
    get:
      operationId: getBookingSettings
      tags:
        - Appointments
      summary: Retrieve booking settings
      description: Returns the account's services, locations, and practitioners.
      responses:
        '200':
          description: Booking settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Services:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  Locations:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  Practitioners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Practitioner'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments/cancellation:
    post:
      operationId: cancelAppointment
      tags:
        - Appointments
      summary: Cancel an appointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - AppointmentId
              properties:
                AppointmentId:
                  type: string
                Reason:
                  type: string
      responses:
        '200':
          description: The appointment was cancelled.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/summary:
    get:
      operationId: queryIntakes
      tags:
        - Intake Forms
      summary: Query intake form summaries
      parameters:
        - name: client
          in: query
          schema:
            type: string
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of intake summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntakeSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/{intakeId}:
    get:
      operationId: getIntake
      tags:
        - Intake Forms
      summary: Retrieve a complete intake form
      parameters:
        - name: intakeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The full intake form as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/{intakeId}/pdf:
    get:
      operationId: downloadIntakePdf
      tags:
        - Intake Forms
      summary: Download an intake package as PDF
      parameters:
        - name: intakeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The intake package PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/{intakeId}/consent/{consentFormId}/pdf:
    get:
      operationId: downloadConsentPdf
      tags:
        - Intake Forms
      summary: Download a single consent form as PDF
      parameters:
        - name: intakeId
          in: path
          required: true
          schema:
            type: string
        - name: consentFormId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The consent form PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/send:
    post:
      operationId: sendIntake
      tags:
        - Intake Forms
      summary: Send an intake questionnaire to a client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The questionnaire was sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes/resend:
    post:
      operationId: resendIntake
      tags:
        - Intake Forms
      summary: Resend a previously sent intake
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The questionnaire was resent.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intakes:
    post:
      operationId: updateIntakeOfficeAnswers
      tags:
        - Intake Forms
      summary: Update office-use-only answers on an intake
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The intake was updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /questionnaires:
    get:
      operationId: listQuestionnaires
      tags:
        - Intake Forms
      summary: List questionnaire templates
      responses:
        '200':
          description: A list of questionnaire templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /practitioners:
    get:
      operationId: listPractitioners
      tags:
        - Intake Forms
      summary: List account practitioners
      responses:
        '200':
          description: A list of practitioners.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Practitioner'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /notes/summary:
    get:
      operationId: queryTreatmentNotes
      tags:
        - Treatment Notes
      summary: Query treatment note summaries
      parameters:
        - name: client
          in: query
          schema:
            type: string
        - name: clientId
          in: query
          schema:
            type: integer
        - name: status
          in: query
          schema:
            type: integer
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: page
          in: query
          schema:
            type: integer
        - name: updatedSince
          in: query
          schema:
            type: string
            format: date
        - name: deletedOnly
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: A list of treatment note summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TreatmentNoteSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /notes/{noteId}:
    get:
      operationId: getTreatmentNote
      tags:
        - Treatment Notes
      summary: Retrieve a full treatment note
      parameters:
        - name: noteId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The full treatment note as JSON.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /notes/{noteId}/pdf:
    get:
      operationId: downloadTreatmentNotePdf
      tags:
        - Treatment Notes
      summary: Download a treatment note as PDF
      parameters:
        - name: noteId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The treatment note PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices:
    get:
      operationId: queryInvoices
      tags:
        - Invoices
      summary: Query invoices
      description: Returns a maximum of 100 records per request.
      parameters:
        - name: clientId
          in: query
          schema:
            type: integer
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: status
          in: query
          schema:
            type: string
        - name: practitionerEmail
          in: query
          schema:
            type: string
        - name: number
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: lastUpdatedStartDate
          in: query
          schema:
            type: string
            format: date
        - name: lastUpdatedEndDate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/{invoiceId}:
    get:
      operationId: getInvoice
      tags:
        - Invoices
      summary: Retrieve a single invoice
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /files:
    get:
      operationId: getClientFiles
      tags:
        - Files
      summary: Get a client's files
      parameters:
        - name: clientId
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A list of the client's files.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /folders:
    get:
      operationId: getFolders
      tags:
        - Files
      summary: Get folders
      responses:
        '200':
          description: A list of folders.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /files/{fileId}:
    get:
      operationId: downloadFile
      tags:
        - Files
      summary: Download a file
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The file contents.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteFile
      tags:
        - Files
      summary: Delete a file
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The file was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /files/{clientId}:
    post:
      operationId: uploadFile
      tags:
        - Files
      summary: Upload a file to a client's record
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The uploaded file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    authKey:
      type: apiKey
      in: header
      name: X-Auth-Key
      description: >-
        The account API key found under More > Settings > Integrations >
        Developer API.
  responses:
    Unauthorized:
      description: Missing or invalid X-Auth-Key.
    RateLimited:
      description: >-
        Rate limit exceeded (standard subscription allows 10 requests/minute,
        max 500/day).
  schemas:
    Client:
      type: object
      properties:
        ClientId:
          type: integer
        Name:
          type: string
        FirstName:
          type: string
        LastName:
          type: string
        Email:
          type: string
        Phone:
          type: string
        DateOfBirth:
          type: string
        ExternalClientId:
          type: string
        Tags:
          type: array
          items:
            type: string
        Archived:
          type: boolean
      additionalProperties: true
    Appointment:
      type: object
      properties:
        Id:
          type: string
        ClientId:
          type: integer
        ClientName:
          type: string
        PractitionerId:
          type: string
        ServiceId:
          type: string
        ServiceName:
          type: string
        LocationId:
          type: string
        Status:
          type: string
        StartDate:
          type: integer
          description: Unix timestamp (ms) of the appointment start.
        Duration:
          type: integer
        Price:
          type: number
      additionalProperties: true
    AppointmentCreate:
      type: object
      required:
        - PractitionerId
        - ClientId
        - ServiceId
        - LocationId
        - Status
        - UtcDateTime
        - SendClientEmailNotification
        - ReminderType
      properties:
        PractitionerId:
          type: string
        ClientId:
          type: integer
        ServiceId:
          type: string
        LocationId:
          type: string
        Status:
          type: string
        UtcDateTime:
          type: integer
          description: Appointment time as a UTC Unix timestamp.
        SendClientEmailNotification:
          type: boolean
        ReminderType:
          type: string
    AppointmentUpdate:
      type: object
      required:
        - Id
        - UtcDateTime
      properties:
        Id:
          type: string
        UtcDateTime:
          type: integer
        ServiceId:
          type: string
        LocationId:
          type: string
        Status:
          type: string
        SendClientEmailNotification:
          type: boolean
        ReminderType:
          type: string
    Practitioner:
      type: object
      properties:
        Id:
          type: string
        CompleteName:
          type: string
        Email:
          type: string
      additionalProperties: true
    IntakeSummary:
      type: object
      properties:
        Id:
          type: string
        ClientName:
          type: string
        ClientId:
          type: integer
        DateCreated:
          type: integer
        Status:
          type: string
        QuestionnaireName:
          type: string
      additionalProperties: true
    TreatmentNoteSummary:
      type: object
      properties:
        Id:
          type: string
        ClientName:
          type: string
        ClientId:
          type: integer
        Status:
          type: integer
        Date:
          type: integer
        NoteName:
          type: string
      additionalProperties: true
    Invoice:
      type: object
      properties:
        Id:
          type: string
        Number:
          type: string
        ClientId:
          type: integer
        ClientName:
          type: string
        Status:
          type: string
        TotalAmount:
          type: number
        AmountPaid:
          type: number
        Currency:
          type: string
        DateIssued:
          type: integer
      additionalProperties: true
    File:
      type: object
      properties:
        Id:
          type: string
        FileName:
          type: string
        ContentType:
          type: string
        DateCreated:
          type: integer
      additionalProperties: true