openapi: 3.0.3
info:
  title: Cliniko Appointment Types Patients API
  description: 'Cliniko is practice management software for allied health practices and clinics. This is a representative subset of the public Cliniko REST API, grounded in the official documentation at https://docs.api.cliniko.com and the redguava/cliniko-api GitHub repository. It is not the complete surface - Cliniko documents 50+ resources (appointment types, attendees, availability blocks, billable items, bookings, businesses, communications, concession types, contacts, group appointments, individual appointments, invoices, invoice items, medical alerts, patients, patient attachments, patient cases, patient forms, practitioners, products, recalls, referral sources, services, settings, stock adjustments, taxes, treatment notes, users, and more).

    Base URL is region-sharded. The shard is the suffix on your API key (for example a key ending `-uk1` is served from `https://api.uk1.cliniko.com`); keys with no suffix belong to the `au1` shard. All paths are prefixed with `/v1`.

    Authentication is HTTP Basic: the API key is the username and the password is empty (`-u API_KEY:`). Every request MUST also send an `Accept: application/json` header and a `User-Agent` header of the form `APP_VENDOR_NAME (APP_VENDOR_EMAIL)` containing a valid contact email, or requests may be automatically blocked. Requests are rate limited to 200 per minute per user; a `429` response includes an `X-RateLimit-Reset` header with a UNIX timestamp.

    Modeled note - the field sets below are drawn from the documented example responses; some optional attributes may be omitted, and request-body schemas are representative rather than exhaustive.'
  version: v1
  contact:
    name: Cliniko API Support
    url: https://docs.api.cliniko.com/
  license:
    name: Proprietary
    url: https://www.cliniko.com/terms/
servers:
- url: https://api.{shard}.cliniko.com/v1
  description: Cliniko region-sharded API. The shard is the suffix on your API key.
  variables:
    shard:
      default: au1
      enum:
      - au1
      - au2
      - au3
      - au4
      - uk1
      - eu1
      - us1
      - ca1
      description: Region shard derived from the API key suffix. Keys without a suffix use au1.
security:
- basicAuth: []
tags:
- name: Patients
  description: The people who book in for appointments.
paths:
  /patients:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    get:
      operationId: listPatients
      tags:
      - Patients
      summary: Get patients
      description: Returns a paginated list of all patients.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Query'
      responses:
        '200':
          description: A paginated list of patients.
          content:
            application/json:
              schema:
                type: object
                properties:
                  patients:
                    type: array
                    items:
                      $ref: '#/components/schemas/Patient'
                  total_entries:
                    type: integer
                  links:
                    $ref: '#/components/schemas/Links'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createPatient
      tags:
      - Patients
      summary: Create patient
      description: Creates a new patient.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientInput'
      responses:
        '201':
          description: The created patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /patients/{id}:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getPatient
      tags:
      - Patients
      summary: Get patient
      description: Returns a single patient by ID.
      responses:
        '200':
          description: The requested patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePatient
      tags:
      - Patients
      summary: Update patient
      description: Updates an existing patient.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientInput'
      responses:
        '200':
          description: The updated patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /patients/{id}/archive:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    post:
      operationId: archivePatient
      tags:
      - Patients
      summary: Archive patient
      description: Archives a patient.
      responses:
        '200':
          description: The archived patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /patients/{id}/unarchive:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    post:
      operationId: unarchivePatient
      tags:
      - Patients
      summary: Unarchive patient
      description: Unarchives a previously archived patient.
      responses:
        '200':
          description: The unarchived patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PatientInput:
      type: object
      required:
      - first_name
      - last_name
      properties:
        title:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        preferred_first_name:
          type: string
        email:
          type: string
        date_of_birth:
          type: string
          format: date
        address_1:
          type: string
        city:
          type: string
        state:
          type: string
        post_code:
          type: string
        country:
          type: string
        time_zone:
          type: string
          description: An IANA time zone identifier.
        accepted_privacy_policy:
          type: boolean
          nullable: true
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
    PatientPhoneNumber:
      type: object
      properties:
        phone_type:
          type: string
          example: Mobile
        number:
          type: string
          example: '61444444444'
    Reference:
      type: object
      description: A link to a related resource.
      properties:
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
    Patient:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        preferred_first_name:
          type: string
        email:
          type: string
        date_of_birth:
          type: string
          format: date
        gender:
          type: string
        gender_identity:
          type: string
        pronouns:
          type: string
          nullable: true
        address_1:
          type: string
        address_2:
          type: string
        address_3:
          type: string
        city:
          type: string
        state:
          type: string
        post_code:
          type: string
        country:
          type: string
        occupation:
          type: string
        notes:
          type: string
        appointment_notes:
          type: string
        accepted_privacy_policy:
          type: boolean
          nullable: true
          description: null (no response), true (accepted), or false (rejected).
        accepted_email_marketing:
          type: boolean
          nullable: true
        accepted_sms_marketing:
          type: boolean
          nullable: true
        receives_confirmation_emails:
          type: boolean
        reminder_type:
          type: string
        time_zone:
          type: string
          nullable: true
          description: A valid IANA time zone identifier, or null.
        patient_phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PatientPhoneNumber'
        custom_fields:
          type: object
          additionalProperties: true
        archived_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        appointments:
          $ref: '#/components/schemas/Reference'
        invoices:
          $ref: '#/components/schemas/Reference'
        medical_alerts:
          $ref: '#/components/schemas/Reference'
        links:
          $ref: '#/components/schemas/Links'
    Links:
      type: object
      description: HAL-style pagination and self links.
      properties:
        self:
          type: string
          format: uri
        next:
          type: string
          format: uri
        previous:
          type: string
          format: uri
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. The API is limited to 200 requests per minute per user. The X-RateLimit-Reset header carries a UNIX timestamp for when the window resets.
      headers:
        X-RateLimit-Reset:
          description: UNIX timestamp when the rate-limit window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
    PerPage:
      name: per_page
      in: query
      required: false
      description: Items per page. Default 50, maximum 100.
      schema:
        type: integer
        default: 50
        maximum: 100
    UserAgent:
      name: User-Agent
      in: header
      required: true
      description: Must be of the form `APP_VENDOR_NAME (APP_VENDOR_EMAIL)` and include a valid contact email. Requests without a compliant User-Agent may be automatically blocked.
      schema:
        type: string
        example: MyClinicApp (dev@myclinic.example)
    Page:
      name: page
      in: query
      required: false
      description: Page number (pagination).
      schema:
        type: integer
        default: 1
    Query:
      name: q[]
      in: query
      required: false
      description: Optional filter expression(s). Repeatable.
      schema:
        type: array
        items:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. The API key is the username and the password is left empty (curl: `-u API_KEY:`). The shard suffix on the key selects the base host.'