---
openapi: 3.0.1
info:
  title: API V2
  version: v2
  description: 'Machine-to-machine REST API over the Canonical Data Model. Rate limits:
    authenticated traffic is limited to 300 requests per minute per API client (HTTP
    429 when exceeded). The OAuth token endpoint (POST /oauth/token) is separately
    limited to 10 requests per minute per source IP.'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth2 client_credentials flow. Create an API client in the Connect
        settings to obtain a client id and secret. Authenticate at the token endpoint
        with either HTTP Basic (`Authorization: Basic base64(client_id:client_secret)`)
        or `client_id` and `client_secret` form fields, but not both: two authentication
        methods in one request are rejected with `invalid_request`. `scope` is required.
        Pass a space-separated subset of the scopes the client was granted; omitting
        it, or naming a scope the client does not hold, fails with `invalid_scope`.
        Access tokens expire after two hours and there are no refresh tokens, so request
        another when one expires. Revoking the client refuses its credentials here
        with `unauthorized_client` and rejects the tokens it has already been issued.'
      flows:
        clientCredentials:
          tokenUrl: "/oauth/token"
          scopes:
            patients:read: Read patients
            patients:write: Create and update patients
            scheduler:read: Read scheduler events and video-call join links
            scheduler:write: Create and update scheduler events
            users:read: Read staff members, locations and staff location memberships
            users:write: Update staff external identifiers
            settings:read: Read account settings catalogues
            settings:write: Manage account settings catalogues
            cryo:read: Read the cryostorage inventory
            consents:read: Read consents
            encounters:read: Read encounters (visits)
            webhook_outcomes:write: Report processing outcomes for assigned webhook
              endpoints
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Optional client-generated key (a UUIDv4 is recommended) that makes
        this write safe to retry. Repeating the request with the same key replays
        the original response for 24 hours instead of applying the change twice.
      schema:
        type: string
        maxLength: 255
paths:
  "/api/v2/consents":
    get:
      summary: List consents
      tags:
      - Consents
      security:
      - oauth2:
        - consents:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[patient_id_eq]
        in: query
        required: false
        description: Only consents for this patient
        schema:
          type: integer
      - name: q[status_eq]
        in: query
        required: false
        description: 'CDM status: pending, signed, withdrawn, expired or voided. A
          cancelled or voided case is voided'
        schema:
          type: string
      responses:
        '200':
          description: the account's consents, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.consent record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_consents_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        consent_name:
                          type: string
                          nullable: true
                        cycle_id:
                          type: integer
                          nullable: true
                        issued_by:
                          type: integer
                          nullable: true
                        witnessed_by:
                          type: integer
                          nullable: true
                        consent_type:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        signing_method:
                          type: string
                          nullable: true
                        issue_date:
                          type: string
                          format: date
                          nullable: true
                        expected_submission_date:
                          type: string
                          format: date
                          nullable: true
                        signed_at:
                          type: string
                          format: date-time
                          nullable: true
                        expires_at:
                          type: string
                          format: date-time
                          nullable: true
                        external_document_id:
                          type: string
                          nullable: true
                        signed_document_id:
                          type: integer
                          nullable: true
                        audit_document_id:
                          type: integer
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '403':
          description: the token lacks consents:read
  "/api/v2/consents/{id}":
    get:
      summary: Show a consent
      tags:
      - Consents
      security:
      - oauth2:
        - consents:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the consent in CDM shape, including status
          content:
            application/json:
              schema:
                title: canonical.v0.consent record
                description: The resource's current CDM state, as projected by canonical_v0_consents_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  consent_name:
                    type: string
                    nullable: true
                  cycle_id:
                    type: integer
                    nullable: true
                  issued_by:
                    type: integer
                    nullable: true
                  witnessed_by:
                    type: integer
                    nullable: true
                  consent_type:
                    type: string
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  signing_method:
                    type: string
                    nullable: true
                  issue_date:
                    type: string
                    format: date
                    nullable: true
                  expected_submission_date:
                    type: string
                    format: date
                    nullable: true
                  signed_at:
                    type: string
                    format: date-time
                    nullable: true
                  expires_at:
                    type: string
                    format: date-time
                    nullable: true
                  external_document_id:
                    type: string
                    nullable: true
                  signed_document_id:
                    type: integer
                    nullable: true
                  audit_document_id:
                    type: integer
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such consent in the principal's account
  "/api/v2/cryo/canisters":
    get:
      summary: List cryo canisters
      tags:
      - Cryo canisters
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the account's cryo canisters, paginated in the { data, meta
            } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_canister record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_canisters_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        tank_id:
                          type: integer
                          nullable: true
                        cane_capacity:
                          type: integer
                          nullable: true
                        name:
                          type: string
                          nullable: true
                        color:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/cryo/canisters/{id}":
    get:
      summary: Show a cryo canister
      tags:
      - Cryo canisters
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the cryo canister in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_canister record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_canisters_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  tank_id:
                    type: integer
                    nullable: true
                  cane_capacity:
                    type: integer
                    nullable: true
                  name:
                    type: string
                    nullable: true
                  color:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo canister in the principal's account
  "/api/v2/cryo/devices/{device_id}/contracts":
    get:
      summary: List a cryo device's storage contracts
      tags:
      - Cryo contracts
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the device's cryo storage contracts, paginated in the { data,
            meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_contract record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_contracts_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        issued_to_id:
                          type: integer
                          nullable: true
                        reference_number:
                          type: string
                          nullable: true
                        start_date:
                          type: string
                          format: date
                          nullable: true
                        expiry_date:
                          type: string
                          format: date
                          nullable: true
                        terms_notes:
                          type: string
                          nullable: true
                        invoicing_strategy_name:
                          type: string
                          nullable: true
                        invoicing_strategy_nominal_code:
                          type: string
                          nullable: true
                        draft_at:
                          type: string
                          format: date-time
                          nullable: true
                        expired_at:
                          type: string
                          format: date-time
                          nullable: true
                        delinquent_payments_at:
                          type: string
                          format: date-time
                          nullable: true
                        terminated_at:
                          type: string
                          format: date-time
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such cryo device in the principal's account
  "/api/v2/cryo/devices/{device_id}/contracts/{id}":
    get:
      summary: Show a cryo device's storage contract
      tags:
      - Cryo contracts
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the cryo storage contract in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_contract record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_contracts_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  issued_to_id:
                    type: integer
                    nullable: true
                  reference_number:
                    type: string
                    nullable: true
                  start_date:
                    type: string
                    format: date
                    nullable: true
                  expiry_date:
                    type: string
                    format: date
                    nullable: true
                  terms_notes:
                    type: string
                    nullable: true
                  invoicing_strategy_name:
                    type: string
                    nullable: true
                  invoicing_strategy_nominal_code:
                    type: string
                    nullable: true
                  draft_at:
                    type: string
                    format: date-time
                    nullable: true
                  expired_at:
                    type: string
                    format: date-time
                    nullable: true
                  delinquent_payments_at:
                    type: string
                    format: date-time
                    nullable: true
                  terminated_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo storage contract for this device
  "/api/v2/cryo/devices/{device_id}/thaws":
    get:
      summary: List a cryo device's thaws
      tags:
      - Cryo thaws
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the device's cryo thaws, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_thaw record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_thaws_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        cryo_sample_id:
                          type: integer
                          nullable: true
                        thawed_at:
                          type: string
                          format: date-time
                          nullable: true
                        reason:
                          type: string
                          nullable: true
                        identification:
                          type: string
                          nullable: true
                        cycle_id:
                          type: integer
                          nullable: true
                        thawed_by_id:
                          type: integer
                          nullable: true
                        witnessed_by_id:
                          type: integer
                          nullable: true
                        discarded_by_id:
                          type: integer
                          nullable: true
                        destruction_reason:
                          type: string
                          nullable: true
                        embryos_thawed:
                          type: integer
                          nullable: true
                        embryos_survived:
                          type: integer
                          nullable: true
                        embryos_intact:
                          type: integer
                          nullable: true
                        embryos_cleaving:
                          type: integer
                          nullable: true
                        survival_percentage:
                          type: number
                          nullable: true
                        embryo_type_thawed:
                          type: string
                          nullable: true
                        origin:
                          type: string
                          nullable: true
                        comment:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such cryo device in the principal's account
  "/api/v2/cryo/devices/{device_id}/thaws/{id}":
    get:
      summary: Show a cryo device's thaw
      tags:
      - Cryo thaws
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the cryo thaw in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_thaw record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_thaws_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  cryo_sample_id:
                    type: integer
                    nullable: true
                  thawed_at:
                    type: string
                    format: date-time
                    nullable: true
                  reason:
                    type: string
                    nullable: true
                  identification:
                    type: string
                    nullable: true
                  cycle_id:
                    type: integer
                    nullable: true
                  thawed_by_id:
                    type: integer
                    nullable: true
                  witnessed_by_id:
                    type: integer
                    nullable: true
                  discarded_by_id:
                    type: integer
                    nullable: true
                  destruction_reason:
                    type: string
                    nullable: true
                  embryos_thawed:
                    type: integer
                    nullable: true
                  embryos_survived:
                    type: integer
                    nullable: true
                  embryos_intact:
                    type: integer
                    nullable: true
                  embryos_cleaving:
                    type: integer
                    nullable: true
                  survival_percentage:
                    type: number
                    nullable: true
                  embryo_type_thawed:
                    type: string
                    nullable: true
                  origin:
                    type: string
                    nullable: true
                  comment:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo thaw for this device
  "/api/v2/cryo/devices":
    get:
      summary: List cryo devices
      tags:
      - Cryo devices
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the account's cryo devices, paginated in the { data, meta }
            envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_device record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_devices_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        sample_id:
                          type: integer
                          nullable: true
                        identification:
                          type: string
                          nullable: true
                        device_type:
                          type: string
                          nullable: true
                        count:
                          type: integer
                          nullable: true
                        volume:
                          type: number
                          nullable: true
                        cryo_thaw_id:
                          type: integer
                          nullable: true
                        patient_reserved_for_id:
                          type: integer
                          nullable: true
                        cycle_id:
                          type: integer
                          nullable: true
                        freezing_media:
                          type: string
                          nullable: true
                        freezing_method:
                          type: string
                          nullable: true
                        biopsy:
                          type: string
                          nullable: true
                        freeze_purpose:
                          type: string
                          nullable: true
                        use_status:
                          type: string
                          nullable: true
                        availability:
                          type: string
                          nullable: true
                        fate:
                          type: string
                          nullable: true
                        freeze_date:
                          type: string
                          format: date-time
                          nullable: true
                        expiry_date:
                          type: string
                          format: date
                          nullable: true
                        quarantined_until:
                          type: string
                          format: date
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/cryo/devices/{id}":
    get:
      summary: Show a cryo device
      tags:
      - Cryo devices
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the cryo device in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_device record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_devices_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  sample_id:
                    type: integer
                    nullable: true
                  identification:
                    type: string
                    nullable: true
                  device_type:
                    type: string
                    nullable: true
                  count:
                    type: integer
                    nullable: true
                  volume:
                    type: number
                    nullable: true
                  cryo_thaw_id:
                    type: integer
                    nullable: true
                  patient_reserved_for_id:
                    type: integer
                    nullable: true
                  cycle_id:
                    type: integer
                    nullable: true
                  freezing_media:
                    type: string
                    nullable: true
                  freezing_method:
                    type: string
                    nullable: true
                  biopsy:
                    type: string
                    nullable: true
                  freeze_purpose:
                    type: string
                    nullable: true
                  use_status:
                    type: string
                    nullable: true
                  availability:
                    type: string
                    nullable: true
                  fate:
                    type: string
                    nullable: true
                  freeze_date:
                    type: string
                    format: date-time
                    nullable: true
                  expiry_date:
                    type: string
                    format: date
                    nullable: true
                  quarantined_until:
                    type: string
                    format: date
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo device in the principal's account
  "/api/v2/cryo/locations":
    get:
      summary: List cryo locations
      tags:
      - Cryo locations
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the account's cryo locations, paginated in the { data, meta
            } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_location record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_locations_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        device_id:
                          type: integer
                          nullable: true
                        canister_id:
                          type: integer
                          nullable: true
                        cane:
                          type: string
                          nullable: true
                        cane_position:
                          type: string
                          nullable: true
                        cane_position_color_1:
                          type: string
                          nullable: true
                        cane_position_color_2:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/cryo/locations/{id}":
    get:
      summary: Show a cryo location
      tags:
      - Cryo locations
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the cryo location in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_location record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_locations_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  device_id:
                    type: integer
                    nullable: true
                  canister_id:
                    type: integer
                    nullable: true
                  cane:
                    type: string
                    nullable: true
                  cane_position:
                    type: string
                    nullable: true
                  cane_position_color_1:
                    type: string
                    nullable: true
                  cane_position_color_2:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo location in the principal's account
  "/api/v2/cryo/samples":
    get:
      summary: List cryo samples
      tags:
      - Cryo samples
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the account's cryo samples, paginated in the { data, meta }
            envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_sample record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_samples_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        sample_id:
                          type: string
                          nullable: true
                        sample_type:
                          type: string
                          nullable: true
                        freeze_date:
                          type: string
                          format: date
                          nullable: true
                        cryo_status:
                          type: string
                          nullable: true
                        cane:
                          type: string
                          nullable: true
                        partner_id:
                          type: integer
                          nullable: true
                        oocytes_provider_id:
                          type: integer
                          nullable: true
                        sperm_provider_id:
                          type: integer
                          nullable: true
                        gametes_provider_id:
                          type: integer
                          nullable: true
                        straw_colour:
                          type: string
                          nullable: true
                        expiry_date:
                          type: string
                          format: date
                          nullable: true
                        quarantined_until:
                          type: string
                          format: date
                          nullable: true
                        position:
                          type: string
                          nullable: true
                        total_oocytes_frozen:
                          type: integer
                          nullable: true
                        total_volume_frozen:
                          type: number
                          nullable: true
                        stage_at_freeze:
                          type: string
                          nullable: true
                        devices_count:
                          type: integer
                          nullable: true
                        virology_statuses:
                          type: array
                          items:
                            type: string
                          nullable: true
                        oocyte_provider_virology_statuses:
                          type: array
                          items:
                            type: string
                          nullable: true
                        sperm_provider_virology_statuses:
                          type: array
                          items:
                            type: string
                          nullable: true
                        hfea_gamete_source:
                          type: string
                          nullable: true
                        stored_at:
                          type: string
                          format: date-time
                          nullable: true
                        notes:
                          type: string
                          nullable: true
                        imported_from:
                          type: string
                          nullable: true
                        exported_to:
                          type: string
                          nullable: true
                        frozen_by_id:
                          type: integer
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/cryo/samples/{id}":
    get:
      summary: Show a cryo sample
      tags:
      - Cryo samples
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the cryo sample in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_sample record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_samples_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  sample_id:
                    type: string
                    nullable: true
                  sample_type:
                    type: string
                    nullable: true
                  freeze_date:
                    type: string
                    format: date
                    nullable: true
                  cryo_status:
                    type: string
                    nullable: true
                  cane:
                    type: string
                    nullable: true
                  partner_id:
                    type: integer
                    nullable: true
                  oocytes_provider_id:
                    type: integer
                    nullable: true
                  sperm_provider_id:
                    type: integer
                    nullable: true
                  gametes_provider_id:
                    type: integer
                    nullable: true
                  straw_colour:
                    type: string
                    nullable: true
                  expiry_date:
                    type: string
                    format: date
                    nullable: true
                  quarantined_until:
                    type: string
                    format: date
                    nullable: true
                  position:
                    type: string
                    nullable: true
                  total_oocytes_frozen:
                    type: integer
                    nullable: true
                  total_volume_frozen:
                    type: number
                    nullable: true
                  stage_at_freeze:
                    type: string
                    nullable: true
                  devices_count:
                    type: integer
                    nullable: true
                  virology_statuses:
                    type: array
                    items:
                      type: string
                    nullable: true
                  oocyte_provider_virology_statuses:
                    type: array
                    items:
                      type: string
                    nullable: true
                  sperm_provider_virology_statuses:
                    type: array
                    items:
                      type: string
                    nullable: true
                  hfea_gamete_source:
                    type: string
                    nullable: true
                  stored_at:
                    type: string
                    format: date-time
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  imported_from:
                    type: string
                    nullable: true
                  exported_to:
                    type: string
                    nullable: true
                  frozen_by_id:
                    type: integer
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo sample in the principal's account
  "/api/v2/cryo/tanks":
    get:
      summary: List cryo tanks
      tags:
      - Cryo tanks
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the account's cryo tanks, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cryo_tank record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cryo_tanks_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        location:
                          type: string
                          nullable: true
                        tank_type:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        location_id:
                          type: integer
                          nullable: true
                        color:
                          type: string
                          nullable: true
                        canister_capacity:
                          type: integer
                          nullable: true
                        eggs:
                          type: boolean
                          nullable: true
                        embryos:
                          type: boolean
                          nullable: true
                        sperm:
                          type: boolean
                          nullable: true
                        donor_eggs:
                          type: boolean
                          nullable: true
                        donor_embryos:
                          type: boolean
                          nullable: true
                        donor_sperm:
                          type: boolean
                          nullable: true
                        service_start_date:
                          type: string
                          format: date
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/cryo/tanks/{id}":
    get:
      summary: Show a cryo tank
      tags:
      - Cryo tanks
      security:
      - oauth2:
        - cryo:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '403':
          description: the client is restricted to clinics but cryo inventory is account-level
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '200':
          description: the cryo tank in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cryo_tank record
                description: The resource's current CDM state, as projected by canonical_v0_cryo_tanks_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  location:
                    type: string
                    nullable: true
                  tank_type:
                    type: string
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  color:
                    type: string
                    nullable: true
                  canister_capacity:
                    type: integer
                    nullable: true
                  eggs:
                    type: boolean
                    nullable: true
                  embryos:
                    type: boolean
                    nullable: true
                  sperm:
                    type: boolean
                    nullable: true
                  donor_eggs:
                    type: boolean
                    nullable: true
                  donor_embryos:
                    type: boolean
                    nullable: true
                  donor_sperm:
                    type: boolean
                    nullable: true
                  service_start_date:
                    type: string
                    format: date
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such cryo tank in the principal's account
  "/api/v2/encounters":
    get:
      summary: List encounters
      tags:
      - Encounters
      security:
      - oauth2:
        - encounters:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[patient_id_eq]
        in: query
        required: false
        description: Only this patient's encounters
        schema:
          type: integer
      - name: q[scheduler_event_id_eq]
        in: query
        required: false
        description: Only the encounter for this scheduler event (the appointment
          the patient attended)
        schema:
          type: integer
      - name: q[updated_at_gteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Updated at or after (ISO8601), compared with the encounter's
          updated_at
      - name: include
        in: query
        required: false
        description: 'Child resources to return under top-level `included`: `encounter_participants`
          (the clinicians) and `patient_diagnoses` (the ICD-10 codes recorded at the
          visit, with `is_principal`). Comma-separated. An unknown value is 400. Show
          wraps the record in `{ data, included }` when this is present.'
        schema:
          type: string
      responses:
        '200':
          description: the account's encounters, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.encounter record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_encounters_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        location_id:
                          type: integer
                          nullable: true
                        scheduler_event_id:
                          type: integer
                          nullable: true
                        cycle_id:
                          type: integer
                          nullable: true
                        mode_of_contact:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        arrived_at:
                          type: string
                          format: date-time
                          nullable: true
                        departed_at:
                          type: string
                          format: date-time
                          nullable: true
                        start_at:
                          type: string
                          format: date-time
                          nullable: true
                        end_at:
                          type: string
                          format: date-time
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
                  included:
                    type: object
                    properties:
                      encounter_participants:
                        type: array
                        items:
                          title: canonical.v0.encounter_participant record
                          description: The resource's current CDM state, as projected
                            by canonical_v0_encounter_participants_v01. Generated
                            from the vendored CDM DDL, so it cannot fall behind the
                            columns the view returns.
                          type: object
                          required:
                          - id
                          properties:
                            id:
                              type: integer
                            encounter_id:
                              type: integer
                              nullable: true
                            user_id:
                              type: integer
                              nullable: true
                            source_system:
                              type: string
                              nullable: true
                            deleted:
                              type: string
                              format: date-time
                              description: Soft-delete timestamp; null when the record
                                is live
                              nullable: true
                            created_at:
                              type: string
                              format: date-time
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
                      patient_diagnoses:
                        type: array
                        items:
                          title: canonical.v0.patient_diagnosis record
                          description: The resource's current CDM state, as projected
                            by canonical_v0_patient_diagnoses_v01. Generated from
                            the vendored CDM DDL, so it cannot fall behind the columns
                            the view returns.
                          type: object
                          required:
                          - id
                          properties:
                            id:
                              type: integer
                            patient_id:
                              type: integer
                              nullable: true
                            diagnosis_label:
                              type: string
                              nullable: true
                            encounter_id:
                              type: integer
                              nullable: true
                            diagnosed_by:
                              type: integer
                              nullable: true
                            diagnosis_code:
                              type: string
                              nullable: true
                            diagnosis_code_source:
                              type: string
                              nullable: true
                            category:
                              type: string
                              nullable: true
                            is_active:
                              type: boolean
                              nullable: true
                            onset_date:
                              type: string
                              format: date
                              nullable: true
                            resolved_date:
                              type: string
                              format: date
                              nullable: true
                            sort_order:
                              type: integer
                              nullable: true
                            is_principal:
                              type: boolean
                              nullable: true
                            notes:
                              type: string
                              nullable: true
                            source_system:
                              type: string
                              nullable: true
                            deleted:
                              type: string
                              format: date-time
                              description: Soft-delete timestamp; null when the record
                                is live
                              nullable: true
                            created_at:
                              type: string
                              format: date-time
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
        '403':
          description: the token lacks encounters:read
  "/api/v2/encounters/{id}":
    get:
      summary: Show an encounter
      tags:
      - Encounters
      security:
      - oauth2:
        - encounters:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: include
        in: query
        required: false
        description: 'Child resources to return under top-level `included`: `encounter_participants`
          (the clinicians) and `patient_diagnoses` (the ICD-10 codes recorded at the
          visit, with `is_principal`). Comma-separated. An unknown value is 400. Show
          wraps the record in `{ data, included }` when this is present.'
        schema:
          type: string
      responses:
        '200':
          description: the encounter in CDM shape, with arrival and departure
          content:
            application/json:
              schema:
                title: canonical.v0.encounter record
                description: The resource's current CDM state, as projected by canonical_v0_encounters_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  scheduler_event_id:
                    type: integer
                    nullable: true
                  cycle_id:
                    type: integer
                    nullable: true
                  mode_of_contact:
                    type: string
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  arrived_at:
                    type: string
                    format: date-time
                    nullable: true
                  departed_at:
                    type: string
                    format: date-time
                    nullable: true
                  start_at:
                    type: string
                    format: date-time
                    nullable: true
                  end_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such encounter in the principal's account
  "/api/v2/locations":
    get:
      summary: List locations
      tags:
      - Locations
      security:
      - oauth2:
        - users:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the principal's clinics as CDM locations, paginated in the
            { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.location record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_locations_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        location_type:
                          type: string
                          nullable: true
                          description: "`clinic` or `satellite`"
                        facility_licence_number:
                          type: string
                          nullable: true
                        address_line_1:
                          type: string
                          nullable: true
                        town_or_city:
                          type: string
                          nullable: true
                        country:
                          type: string
                          nullable: true
                        state_or_province:
                          type: string
                          nullable: true
                        postal_code:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '403':
          description: users:read is required; scheduler:read alone is insufficient
  "/api/v2/locations/{id}":
    get:
      summary: Show a location
      tags:
      - Locations
      security:
      - oauth2:
        - users:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the location in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.location record
                description: The resource's current CDM state, as projected by canonical_v0_locations_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  location_type:
                    type: string
                    nullable: true
                    description: "`clinic` or `satellite`"
                  facility_licence_number:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postal_code:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such location in the principal's scope
        '403':
          description: users:read is required; scheduler:read alone is insufficient
  "/api/v2/users/{user_id}/locations":
    get:
      summary: List a staff member's locations
      tags:
      - Users
      security:
      - oauth2:
        - users:read
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: assigned locations in the client's account and clinic scope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.location record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_locations_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        location_type:
                          type: string
                          nullable: true
                          description: "`clinic` or `satellite`"
                        facility_licence_number:
                          type: string
                          nullable: true
                        address_line_1:
                          type: string
                          nullable: true
                        town_or_city:
                          type: string
                          nullable: true
                        country:
                          type: string
                          nullable: true
                        state_or_province:
                          type: string
                          nullable: true
                        postal_code:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no active staff membership in the client's account
        '403':
          description: users:read is required; scheduler:read alone is insufficient
  "/api/v2/me":
    get:
      summary: Show the authenticated principal
      tags:
      - Principal
      security:
      - oauth2: []
      responses:
        '200':
          description: authenticated
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - name
                - scopes
                - account_id
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  clinic_ids:
                    type: array
                    items:
                      type: integer
                    nullable: true
                  account_id:
                    type: integer
        '401':
          description: missing or invalid bearer token
  "/api/v2/patients/{patient_id}/diagnoses":
    get:
      summary: List a patient's diagnoses
      tags:
      - Patient diagnoses
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the patient's diagnoses, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient_diagnosis record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patient_diagnoses_v01. Generated from the
                        vendored CDM DDL, so it cannot fall behind the columns the
                        view returns.
                      type: object
                      required:
                      - id
                      - patient_id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        diagnosis_label:
                          type: string
                          nullable: true
                        encounter_id:
                          type: integer
                          nullable: true
                        diagnosed_by:
                          type: integer
                          nullable: true
                        diagnosis_code:
                          type: string
                          nullable: true
                        diagnosis_code_source:
                          type: string
                          nullable: true
                        category:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        onset_date:
                          type: string
                          format: date
                          nullable: true
                        resolved_date:
                          type: string
                          format: date
                          nullable: true
                        sort_order:
                          type: integer
                          nullable: true
                        is_principal:
                          type: boolean
                          nullable: true
                        notes:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such patient in the principal's scope
  "/api/v2/patients/{patient_id}/diagnoses/{id}":
    get:
      summary: Show a patient diagnosis
      tags:
      - Patient diagnoses
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the diagnosis in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient_diagnosis record
                description: The resource's current CDM state, as projected by canonical_v0_patient_diagnoses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  diagnosis_label:
                    type: string
                    nullable: true
                  encounter_id:
                    type: integer
                    nullable: true
                  diagnosed_by:
                    type: integer
                    nullable: true
                  diagnosis_code:
                    type: string
                    nullable: true
                  diagnosis_code_source:
                    type: string
                    nullable: true
                  category:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                  onset_date:
                    type: string
                    format: date
                    nullable: true
                  resolved_date:
                    type: string
                    format: date
                    nullable: true
                  sort_order:
                    type: integer
                    nullable: true
                  is_principal:
                    type: boolean
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such diagnosis for this patient
  "/api/v2/patients/{patient_id}/external_identifiers":
    get:
      summary: List a patient's external identifiers
      tags:
      - Patient external identifiers
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the patient's external identifiers, including document types
            that do not yet have a value, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient_external_identifier record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patient_external_identifiers_v01. Generated
                        from the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        identifier_type:
                          type: string
                          nullable: true
                          description: Either one of the CDM's own document types
                            — health_card, passport, nhs, insurance_membership, rodne_cislo,
                            pps, bsn, cnp, codice_fiscale, ihi, emirates_id, uae_unified_number,
                            or custom for the clinic's ID Number — or an externally-sourced
                            type under the custom- namespace, e.g. custom-MRN. Document
                            types are writable here when enabled in Settings > Patient
                            Identification. SSN identifiers are not returned or writable
                            on this API.
                        identifier_value:
                          type: string
                          nullable: true
                        issuing_jurisdiction:
                          type: string
                          nullable: true
                          description: The authority that issued the identifier, as
                            an ISO 3166-1 alpha-2 country code (GB, DK). Free text,
                            so not validated against that list.
                        valid_from:
                          type: string
                          format: date
                          nullable: true
                          description: 'Read-only, and always null on this resource:
                            nothing populates it yet.'
                        valid_to:
                          type: string
                          format: date
                          nullable: true
                          description: The document expiry for types that have one
                            (passport, health_card, custom). Writable on those types;
                            always null on an externally-sourced identifier.
                        source_system:
                          type: string
                          nullable: true
                          description: 'Read-only provenance: which system the record
                            came from. Always wawa for one written through this API.'
                        deleted:
                          type: string
                          format: date-time
                          description: Read-only. Null while the identifier is live,
                            and set to the time it was discarded by DELETE.
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                        primary:
                          type: boolean
                          description: Whether this is the patient's primary identifier.
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such patient in the principal's scope
    post:
      summary: Create a patient external identifier
      tags:
      - Patient external identifiers
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: the created identifier in CDM shape; one canonical.v0.patient_external_identifier.created
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_external_identifier record
                description: The resource's current CDM state, as projected by canonical_v0_patient_external_identifiers_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  identifier_type:
                    type: string
                    nullable: true
                    description: Either one of the CDM's own document types — health_card,
                      passport, nhs, insurance_membership, rodne_cislo, pps, bsn,
                      cnp, codice_fiscale, ihi, emirates_id, uae_unified_number, or
                      custom for the clinic's ID Number — or an externally-sourced
                      type under the custom- namespace, e.g. custom-MRN. Document
                      types are writable here when enabled in Settings > Patient Identification.
                      SSN identifiers are not returned or writable on this API.
                  identifier_value:
                    type: string
                    nullable: true
                  issuing_jurisdiction:
                    type: string
                    nullable: true
                    description: The authority that issued the identifier, as an ISO
                      3166-1 alpha-2 country code (GB, DK). Free text, so not validated
                      against that list.
                  valid_from:
                    type: string
                    format: date
                    nullable: true
                    description: 'Read-only, and always null on this resource: nothing
                      populates it yet.'
                  valid_to:
                    type: string
                    format: date
                    nullable: true
                    description: The document expiry for types that have one (passport,
                      health_card, custom). Writable on those types; always null on
                      an externally-sourced identifier.
                  source_system:
                    type: string
                    nullable: true
                    description: 'Read-only provenance: which system the record came
                      from. Always wawa for one written through this API.'
                  deleted:
                    type: string
                    format: date-time
                    description: Read-only. Null while the identifier is live, and
                      set to the time it was discarded by DELETE.
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  primary:
                    type: boolean
                    description: Whether this is the patient's primary identifier.
        '422':
          description: the identifier is invalid (duplicate type, disabled document
            type, blank value)
        '404':
          description: no such patient in the principal's scope
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                primary:
                  type: boolean
                  description: Optional, defaults to false. Only one kept identifier
                    per patient can be primary. Clear the existing primary before
                    selecting another; a second primary returns 422.
                identifier_type:
                  type: string
                  description: Either a CDM document type (health_card, passport,
                    nhs, insurance_membership, rodne_cislo, pps, bsn, cnp, codice_fiscale,
                    ihi, emirates_id, uae_unified_number, or custom for the clinic's
                    ID Number) or the issuing system's own name, namespaced as it
                    reads back, e.g. custom-MRN. A type that is neither is rejected.
                    Document types are gated by Settings > Patient Identification;
                    a namespaced type is not. Health card variant (OHIP, RAMQ, …)
                    is not a field on this resource. SSN is omitted from this API.
                identifier_value:
                  type: string
                  description: The identifier itself. Cannot be blank. An emirates_id
                    is 15 digits starting with 784; hyphens and spaces are stripped,
                    so 784-YYYY-NNNNNNN-C is accepted and stored as the digits. A
                    uae_unified_number is digits only, at most 40. Any other value
                    for those types is rejected as 422.
                issuing_jurisdiction:
                  type: string
                  description: Optional. The authority that issued the identifier,
                    as an ISO 3166-1 alpha-2 country code (GB, DK). Free text, so
                    not validated against that list.
                valid_to:
                  type: string
                  format: date
                  description: Optional. The document expiry, accepted on passport,
                    health_card and custom. Rejected as 400 on every other type. valid_from
                    is always read-only.
              required:
              - identifier_type
              - identifier_value
  "/api/v2/patients/{patient_id}/external_identifiers/{id}":
    get:
      summary: Show a patient external identifier
      tags:
      - Patient external identifiers
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the external identifier in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient_external_identifier record
                description: The resource's current CDM state, as projected by canonical_v0_patient_external_identifiers_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  identifier_type:
                    type: string
                    nullable: true
                    description: Either one of the CDM's own document types — health_card,
                      passport, nhs, insurance_membership, rodne_cislo, pps, bsn,
                      cnp, codice_fiscale, ihi, emirates_id, uae_unified_number, or
                      custom for the clinic's ID Number — or an externally-sourced
                      type under the custom- namespace, e.g. custom-MRN. Document
                      types are writable here when enabled in Settings > Patient Identification.
                      SSN identifiers are not returned or writable on this API.
                  identifier_value:
                    type: string
                    nullable: true
                  issuing_jurisdiction:
                    type: string
                    nullable: true
                    description: The authority that issued the identifier, as an ISO
                      3166-1 alpha-2 country code (GB, DK). Free text, so not validated
                      against that list.
                  valid_from:
                    type: string
                    format: date
                    nullable: true
                    description: 'Read-only, and always null on this resource: nothing
                      populates it yet.'
                  valid_to:
                    type: string
                    format: date
                    nullable: true
                    description: The document expiry for types that have one (passport,
                      health_card, custom). Writable on those types; always null on
                      an externally-sourced identifier.
                  source_system:
                    type: string
                    nullable: true
                    description: 'Read-only provenance: which system the record came
                      from. Always wawa for one written through this API.'
                  deleted:
                    type: string
                    format: date-time
                    description: Read-only. Null while the identifier is live, and
                      set to the time it was discarded by DELETE.
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  primary:
                    type: boolean
                    description: Whether this is the patient's primary identifier.
        '404':
          description: no such identifier for this patient
    patch:
      summary: Update a patient external identifier
      tags:
      - Patient external identifiers
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated identifier in CDM shape; one canonical.v0.patient_external_identifier.updated
            event is published when something changed
          content:
            application/json:
              schema:
                title: canonical.v0.patient_external_identifier record
                description: The resource's current CDM state, as projected by canonical_v0_patient_external_identifiers_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  identifier_type:
                    type: string
                    nullable: true
                    description: Either one of the CDM's own document types — health_card,
                      passport, nhs, insurance_membership, rodne_cislo, pps, bsn,
                      cnp, codice_fiscale, ihi, emirates_id, uae_unified_number, or
                      custom for the clinic's ID Number — or an externally-sourced
                      type under the custom- namespace, e.g. custom-MRN. Document
                      types are writable here when enabled in Settings > Patient Identification.
                      SSN identifiers are not returned or writable on this API.
                  identifier_value:
                    type: string
                    nullable: true
                  issuing_jurisdiction:
                    type: string
                    nullable: true
                    description: The authority that issued the identifier, as an ISO
                      3166-1 alpha-2 country code (GB, DK). Free text, so not validated
                      against that list.
                  valid_from:
                    type: string
                    format: date
                    nullable: true
                    description: 'Read-only, and always null on this resource: nothing
                      populates it yet.'
                  valid_to:
                    type: string
                    format: date
                    nullable: true
                    description: The document expiry for types that have one (passport,
                      health_card, custom). Writable on those types; always null on
                      an externally-sourced identifier.
                  source_system:
                    type: string
                    nullable: true
                    description: 'Read-only provenance: which system the record came
                      from. Always wawa for one written through this API.'
                  deleted:
                    type: string
                    format: date-time
                    description: Read-only. Null while the identifier is live, and
                      set to the time it was discarded by DELETE.
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  primary:
                    type: boolean
                    description: Whether this is the patient's primary identifier.
        '403':
          description: the identifier is readable but not the caller's to change
        '422':
          description: another kept identifier is already primary
        '404':
          description: no such identifier for this patient
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                primary:
                  type: boolean
                  description: Optional, defaults to false. Only one kept identifier
                    per patient can be primary. Clear the existing primary before
                    selecting another; a second primary returns 422.
                identifier_type:
                  type: string
                  description: Either a CDM document type (health_card, passport,
                    nhs, insurance_membership, rodne_cislo, pps, bsn, cnp, codice_fiscale,
                    ihi, emirates_id, uae_unified_number, or custom for the clinic's
                    ID Number) or the issuing system's own name, namespaced as it
                    reads back, e.g. custom-MRN. A type that is neither is rejected.
                    Document types are gated by Settings > Patient Identification;
                    a namespaced type is not. Health card variant (OHIP, RAMQ, …)
                    is not a field on this resource. SSN is omitted from this API.
                identifier_value:
                  type: string
                  description: The identifier itself. Cannot be blank. An emirates_id
                    is 15 digits starting with 784; hyphens and spaces are stripped,
                    so 784-YYYY-NNNNNNN-C is accepted and stored as the digits. A
                    uae_unified_number is digits only, at most 40. Any other value
                    for those types is rejected as 422.
                issuing_jurisdiction:
                  type: string
                  description: Optional. The authority that issued the identifier,
                    as an ISO 3166-1 alpha-2 country code (GB, DK). Free text, so
                    not validated against that list.
                valid_to:
                  type: string
                  format: date
                  description: Optional. The document expiry, accepted on passport,
                    health_card and custom. Rejected as 400 on every other type. valid_from
                    is always read-only.
    delete:
      summary: Discard a patient external identifier
      tags:
      - Patient external identifiers
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the discarded identifier in CDM shape; one canonical.v0.patient_external_identifier.deleted
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_external_identifier record
                description: The resource's current CDM state, as projected by canonical_v0_patient_external_identifiers_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  identifier_type:
                    type: string
                    nullable: true
                    description: Either one of the CDM's own document types — health_card,
                      passport, nhs, insurance_membership, rodne_cislo, pps, bsn,
                      cnp, codice_fiscale, ihi, emirates_id, uae_unified_number, or
                      custom for the clinic's ID Number — or an externally-sourced
                      type under the custom- namespace, e.g. custom-MRN. Document
                      types are writable here when enabled in Settings > Patient Identification.
                      SSN identifiers are not returned or writable on this API.
                  identifier_value:
                    type: string
                    nullable: true
                  issuing_jurisdiction:
                    type: string
                    nullable: true
                    description: The authority that issued the identifier, as an ISO
                      3166-1 alpha-2 country code (GB, DK). Free text, so not validated
                      against that list.
                  valid_from:
                    type: string
                    format: date
                    nullable: true
                    description: 'Read-only, and always null on this resource: nothing
                      populates it yet.'
                  valid_to:
                    type: string
                    format: date
                    nullable: true
                    description: The document expiry for types that have one (passport,
                      health_card, custom). Writable on those types; always null on
                      an externally-sourced identifier.
                  source_system:
                    type: string
                    nullable: true
                    description: 'Read-only provenance: which system the record came
                      from. Always wawa for one written through this API.'
                  deleted:
                    type: string
                    format: date-time
                    description: Read-only. Null while the identifier is live, and
                      set to the time it was discarded by DELETE.
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  primary:
                    type: boolean
                    description: Whether this is the patient's primary identifier.
        '204':
          description: a seeded identifier that never had a number, discarded to free
            the type with no CDM body
        '403':
          description: the identifier is readable but not the caller's to remove
        '404':
          description: no such identifier for this patient
  "/api/v2/patients/{patient_id}/fund_source":
    patch:
      summary: Assign a patient's fund source
      tags:
      - Patients
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the patient in CDM shape, carrying the assigned fund source
          content:
            application/json:
              schema:
                title: canonical.v0.patient record
                description: The resource's current CDM state, as projected by canonical_v0_patients_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  patient_identity_management_id:
                    type: string
                    nullable: true
                  regulatory_reference_number:
                    type: string
                    nullable: true
                  middle_name:
                    type: string
                    nullable: true
                  preferred_name:
                    type: string
                    nullable: true
                  full_legal_name:
                    type: string
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  sex_assigned_at_birth:
                    type: string
                    nullable: true
                  gender_identity:
                    type: string
                    nullable: true
                  pronouns:
                    type: string
                    nullable: true
                  ethnicity:
                    type: string
                    nullable: true
                  fathers_ethnicity:
                    type: string
                    nullable: true
                  mothers_ethnicity:
                    type: string
                    nullable: true
                  country_of_birth:
                    type: string
                    nullable: true
                  town_or_city_of_birth:
                    type: string
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                  religion:
                    type: string
                    nullable: true
                  preferred_language:
                    type: string
                    nullable: true
                  marital_status:
                    type: string
                    nullable: true
                  blood_group:
                    type: string
                    nullable: true
                  rhesus_factor:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_donor:
                    type: boolean
                    nullable: true
                  is_deceased:
                    type: boolean
                    nullable: true
                  date_of_death:
                    type: string
                    format: date
                    nullable: true
                  is_test_patient:
                    type: boolean
                    nullable: true
                  primary_user_id:
                    type: integer
                    nullable: true
                  brand_id:
                    type: integer
                    nullable: true
                  fund_source_id:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  initial_contact_at:
                    type: string
                    format: date-time
                    nullable: true
                  first_seen_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_last_sent_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_accepted_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_app_connected:
                    type: boolean
                    nullable: true
                  registration_status:
                    type: string
                    nullable: true
                  registration_completion_percentage:
                    type: integer
                    nullable: true
                  care_stage:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_portal_connected:
                    type: boolean
                    description: Whether the patient is connected to the patient portal
                      or app. Read-only.
        '422':
          description: the fund source id is not one of the principal's fund sources
        '404':
          description: no such patient in the principal's scope
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - fund_source_id
              properties:
                fund_source_id:
                  type: integer
                  nullable: true
                  description: The CDM fund source id, or null to leave the patient
                    with no fund source
  "/api/v2/patients/{patient_id}/locations":
    get:
      summary: List a patient's clinic assignments
      tags:
      - Patient locations
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the patient's clinic assignments as CDM patient_locations,
            paginated
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient_location record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patient_locations_v01. Generated from the
                        vendored CDM DDL, so it cannot fall behind the columns the
                        view returns.
                      type: object
                      required:
                      - id
                      - patient_id
                      - location_id
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        location_id:
                          type: integer
                          nullable: true
                          description: Clinic id (CDM locations)
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such patient in the principal's scope
  "/api/v2/patients/{patient_id}/locations/{id}":
    get:
      summary: Show a patient clinic assignment
      tags:
      - Patient locations
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the clinic assignment in CDM patient_locations shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient_location record
                description: The resource's current CDM state, as projected by canonical_v0_patient_locations_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - location_id
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                    description: Clinic id (CDM locations)
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such assignment for this patient
  "/api/v2/patients/{patient_id}/phones":
    get:
      summary: List a patient's phones
      tags:
      - Patient phones
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the patient's kept phone numbers, paginated in the { data,
            meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient_phone record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patient_phones_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - patient_id
                      - phone_number
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        phone_type:
                          type: string
                          nullable: true
                        phone_number:
                          type: string
                          nullable: true
                        country_code:
                          type: string
                          nullable: true
                        preferred_at:
                          type: string
                          format: date-time
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such patient in the principal's scope
    post:
      summary: Create a patient phone
      tags:
      - Patient phones
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: the created phone in CDM shape; one canonical.v0.patient_phone.created
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_phone record
                description: The resource's current CDM state, as projected by canonical_v0_patient_phones_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - phone_number
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  phone_type:
                    type: string
                    nullable: true
                  phone_number:
                    type: string
                    nullable: true
                  country_code:
                    type: string
                    nullable: true
                  preferred_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: a second kept primary is rejected
        '404':
          description: no such patient in the principal's scope
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_type:
                  type: string
                  enum:
                  - primary
                  - mobile
                  - home
                  - work
                  - other
                phone_number:
                  type: string
                country_code:
                  type: string
                preferred_at:
                  type: string
                  format: date-time
                  nullable: true
              required:
              - phone_type
              - phone_number
  "/api/v2/patients/{patient_id}/phones/{id}":
    get:
      summary: Show a patient phone
      tags:
      - Patient phones
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the phone in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient_phone record
                description: The resource's current CDM state, as projected by canonical_v0_patient_phones_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - phone_number
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  phone_type:
                    type: string
                    nullable: true
                  phone_number:
                    type: string
                    nullable: true
                  country_code:
                    type: string
                    nullable: true
                  preferred_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such kept phone for this patient — also the case for a discarded
            phone
    patch:
      summary: Update a patient phone
      tags:
      - Patient phones
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated phone in CDM shape; one canonical.v0.patient_phone.updated
            event is published when something changed
          content:
            application/json:
              schema:
                title: canonical.v0.patient_phone record
                description: The resource's current CDM state, as projected by canonical_v0_patient_phones_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - phone_number
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  phone_type:
                    type: string
                    nullable: true
                  phone_number:
                    type: string
                    nullable: true
                  country_code:
                    type: string
                    nullable: true
                  preferred_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such kept phone for this patient
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_type:
                  type: string
                  enum:
                  - primary
                  - mobile
                  - home
                  - work
                  - other
                phone_number:
                  type: string
                country_code:
                  type: string
                preferred_at:
                  type: string
                  format: date-time
                  nullable: true
    delete:
      summary: Discard a patient phone
      tags:
      - Patient phones
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the discarded phone in CDM shape; one canonical.v0.patient_phone.deleted
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_phone record
                description: The resource's current CDM state, as projected by canonical_v0_patient_phones_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - phone_number
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  phone_type:
                    type: string
                    nullable: true
                  phone_number:
                    type: string
                    nullable: true
                  country_code:
                    type: string
                    nullable: true
                  preferred_at:
                    type: string
                    format: date-time
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such kept phone for this patient — an already-discarded
            phone cannot be discarded again
  "/api/v2/patients/{patient_id}/portal_invitation":
    post:
      summary: Invite a patient to the patient portal
      tags:
      - Patients
      security:
      - oauth2: []
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      description: Queues the clinic invitation email. Already-connected patients
        are a no-op. A second invite inside five minutes is 429. is_portal_connected
        on the patient is read-only.
      responses:
        '200':
          description: the patient in CDM shape; the invitation is queued unless they
            are already connected
          content:
            application/json:
              schema:
                title: canonical.v0.patient record
                description: The resource's current CDM state, as projected by canonical_v0_patients_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  patient_identity_management_id:
                    type: string
                    nullable: true
                  regulatory_reference_number:
                    type: string
                    nullable: true
                  middle_name:
                    type: string
                    nullable: true
                  preferred_name:
                    type: string
                    nullable: true
                  full_legal_name:
                    type: string
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  sex_assigned_at_birth:
                    type: string
                    nullable: true
                  gender_identity:
                    type: string
                    nullable: true
                  pronouns:
                    type: string
                    nullable: true
                  ethnicity:
                    type: string
                    nullable: true
                  fathers_ethnicity:
                    type: string
                    nullable: true
                  mothers_ethnicity:
                    type: string
                    nullable: true
                  country_of_birth:
                    type: string
                    nullable: true
                  town_or_city_of_birth:
                    type: string
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                  religion:
                    type: string
                    nullable: true
                  preferred_language:
                    type: string
                    nullable: true
                  marital_status:
                    type: string
                    nullable: true
                  blood_group:
                    type: string
                    nullable: true
                  rhesus_factor:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_donor:
                    type: boolean
                    nullable: true
                  is_deceased:
                    type: boolean
                    nullable: true
                  date_of_death:
                    type: string
                    format: date
                    nullable: true
                  is_test_patient:
                    type: boolean
                    nullable: true
                  primary_user_id:
                    type: integer
                    nullable: true
                  brand_id:
                    type: integer
                    nullable: true
                  fund_source_id:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  initial_contact_at:
                    type: string
                    format: date-time
                    nullable: true
                  first_seen_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_last_sent_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_accepted_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_app_connected:
                    type: boolean
                    nullable: true
                  registration_status:
                    type: string
                    nullable: true
                  registration_completion_percentage:
                    type: integer
                    nullable: true
                  care_stage:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_portal_connected:
                    type: boolean
                    description: Whether the patient is connected to the patient portal
                      or app. Read-only.
        '429':
          description: an invitation was already sent in the last five minutes
        '422':
          description: the patient has no email address
        '404':
          description: no such patient in the principal's scope
  "/api/v2/patients/{patient_id}/relationships":
    get:
      summary: List a patient's relationships
      tags:
      - Patient relationships
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the patient's active relationships, from both directions of
            the link, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient_relationship record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patient_relationships_v01. Generated from
                        the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      - patient_id
                      - related_patient_id
                      - relationship_type
                      properties:
                        id:
                          type: integer
                        patient_id:
                          type: integer
                          nullable: true
                        related_patient_id:
                          type: integer
                          nullable: true
                        relationship_type:
                          type: string
                          nullable: true
                        same_sex_couple:
                          type: boolean
                          nullable: true
                        active_from:
                          type: string
                          format: date
                          nullable: true
                        active_to:
                          type: string
                          format: date
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such patient in the principal's scope
    post:
      summary: Link a partner
      tags:
      - Patient relationships
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: the created relationship in CDM shape; one canonical.v0.patient_relationship.created
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_relationship record
                description: The resource's current CDM state, as projected by canonical_v0_patient_relationships_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - related_patient_id
                - relationship_type
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  related_patient_id:
                    type: integer
                    nullable: true
                  relationship_type:
                    type: string
                    nullable: true
                  same_sex_couple:
                    type: boolean
                    nullable: true
                  active_from:
                    type: string
                    format: date
                    nullable: true
                  active_to:
                    type: string
                    format: date
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '200':
          description: the patients were already linked — the existing active relationship,
            unchanged, and no event
        '422':
          description: the link is invalid — here a related patient outside the principal's
            scope
        '404':
          description: no such patient in the principal's scope
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - related_patient_id
              - relationship_type
              properties:
                related_patient_id:
                  type: integer
                relationship_type:
                  type: string
                  enum:
                  - partner
                  - married
  "/api/v2/patients/{patient_id}/relationships/{id}":
    get:
      summary: Show a relationship
      tags:
      - Patient relationships
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the relationship in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient_relationship record
                description: The resource's current CDM state, as projected by canonical_v0_patient_relationships_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - related_patient_id
                - relationship_type
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  related_patient_id:
                    type: integer
                    nullable: true
                  relationship_type:
                    type: string
                    nullable: true
                  same_sex_couple:
                    type: boolean
                    nullable: true
                  active_from:
                    type: string
                    format: date
                    nullable: true
                  active_to:
                    type: string
                    format: date
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such active relationship for this patient — also the case
            for an ended link
    delete:
      summary: End a relationship
      tags:
      - Patient relationships
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: patient_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the ended relationship in its final CDM state; one canonical.v0.patient_relationship.ended
            event is published
          content:
            application/json:
              schema:
                title: canonical.v0.patient_relationship record
                description: The resource's current CDM state, as projected by canonical_v0_patient_relationships_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - patient_id
                - related_patient_id
                - relationship_type
                properties:
                  id:
                    type: integer
                  patient_id:
                    type: integer
                    nullable: true
                  related_patient_id:
                    type: integer
                    nullable: true
                  relationship_type:
                    type: string
                    nullable: true
                  same_sex_couple:
                    type: boolean
                    nullable: true
                  active_from:
                    type: string
                    format: date
                    nullable: true
                  active_to:
                    type: string
                    format: date
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such active relationship for this patient — an already-ended
            link cannot be ended again
  "/api/v2/patients":
    get:
      summary: List patients
      tags:
      - Patients
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[search]
        in: query
        required: false
        description: 'Free-text query: name, identity-management id, or date of birth'
        schema:
          type: string
      - name: q[first_name_cont]
        in: query
        required: false
        description: First name contains
        schema:
          type: string
      - name: q[last_name_cont]
        in: query
        required: false
        description: Last name contains
        schema:
          type: string
      - name: q[email_eq]
        in: query
        required: false
        description: Email equals
        schema:
          type: string
      - name: q[date_of_birth_eq]
        in: query
        schema:
          type: string
          format: date
        required: false
        description: Date of birth equals (ISO8601 date)
      - name: q[external_identifier_type_eq]
        in: query
        required: false
        description: Active external identifier type equals, namespaced as it reads
          back (e.g. custom-MRN)
        schema:
          type: string
      - name: q[external_identifier_value_eq]
        in: query
        required: false
        description: Active external identifier value equals; combined with the type
          filter both must match the same identifier
        schema:
          type: string
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      - name: q[updated_at_gteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Updated at or after (ISO8601), compared with the patient's updated_at
      - name: include
        in: query
        required: false
        description: 'Child resources to return under top-level `included`: `patient_phones`,
          `patient_external_identifiers`, or both, comma separated. Join them to their
          patient on `patient_id`. An unknown value is 400. Show wraps the record
          in `{ data, included }` when this is present; without it the body is unchanged.
          A misspelled `includes=` (plural) is ignored.'
        schema:
          type: string
      responses:
        '200':
          description: the principal's patients (matching the q filters when given),
            paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.patient record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_patients_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        first_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                          nullable: true
                        external_identifier:
                          type: string
                          nullable: true
                        title:
                          type: string
                          nullable: true
                        patient_identity_management_id:
                          type: string
                          nullable: true
                        regulatory_reference_number:
                          type: string
                          nullable: true
                        middle_name:
                          type: string
                          nullable: true
                        preferred_name:
                          type: string
                          nullable: true
                        full_legal_name:
                          type: string
                          nullable: true
                        date_of_birth:
                          type: string
                          format: date
                          nullable: true
                        email:
                          type: string
                          nullable: true
                        sex_assigned_at_birth:
                          type: string
                          nullable: true
                          enum:
                          - not_specified
                          - female
                          - male
                        gender_identity:
                          type: string
                          nullable: true
                        pronouns:
                          type: string
                          nullable: true
                        ethnicity:
                          type: string
                          nullable: true
                        fathers_ethnicity:
                          type: string
                          nullable: true
                        mothers_ethnicity:
                          type: string
                          nullable: true
                        country_of_birth:
                          type: string
                          nullable: true
                        town_or_city_of_birth:
                          type: string
                          nullable: true
                        nationality:
                          type: string
                          nullable: true
                          description: ISO 3166-1 alpha-2 country code, uppercase
                            (for example AE, GB, IN)
                        religion:
                          type: string
                          nullable: true
                          enum:
                          - buddhist
                          - christian
                          - hindu
                          - jewish
                          - muslim
                          - sikh
                          - other
                          - no_religion
                          - not_disclosed
                        preferred_language:
                          type: string
                          nullable: true
                          description: 'ISO 639-1 two-letter language code, lowercase
                            (for example en, ro, ar). A full BCP 47 tag is narrowed
                            to its language subtag, so en-GB records as en. Also accepted,
                            for languages ISO 639-1 cannot express: yue, ckb, prs.'
                        marital_status:
                          type: string
                          nullable: true
                          enum:
                          - single
                          - married
                          - separated
                          - divorced
                          - widowed
                          - never_married
                          - in_civil_partnership
                          - separated_still_married
                          - separated_still_civil_partnership
                          - dissolved_civil_partnership
                          - surviving_partner
                          - not_disclosed
                          - cohabiting
                          - in_relationship
                        blood_group:
                          type: string
                          nullable: true
                        rhesus_factor:
                          type: string
                          nullable: true
                        address_line_1:
                          type: string
                          nullable: true
                        address_line_2:
                          type: string
                          nullable: true
                        town_or_city:
                          type: string
                          nullable: true
                        state_or_province:
                          type: string
                          nullable: true
                        postcode:
                          type: string
                          nullable: true
                        country:
                          type: string
                          nullable: true
                        is_donor:
                          type: boolean
                          nullable: true
                        is_deceased:
                          type: boolean
                          nullable: true
                        date_of_death:
                          type: string
                          format: date
                          nullable: true
                        is_test_patient:
                          type: boolean
                          nullable: true
                        primary_user_id:
                          type: integer
                          nullable: true
                        brand_id:
                          type: integer
                          nullable: true
                        fund_source_id:
                          type: integer
                          nullable: true
                        metadata:
                          type: object
                          nullable: true
                        initial_contact_at:
                          type: string
                          format: date-time
                          nullable: true
                        first_seen_at:
                          type: string
                          format: date-time
                          nullable: true
                        app_invitation_last_sent_at:
                          type: string
                          format: date-time
                          nullable: true
                        app_invitation_accepted_at:
                          type: string
                          format: date-time
                          nullable: true
                        is_app_connected:
                          type: boolean
                          nullable: true
                        registration_status:
                          type: string
                          nullable: true
                        registration_completion_percentage:
                          type: integer
                          nullable: true
                        care_stage:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                        is_portal_connected:
                          type: boolean
                          description: Whether the patient is connected to the patient
                            portal or app. Read-only.
                  included:
                    type: object
                    properties:
                      patient_phones:
                        type: array
                        items:
                          title: canonical.v0.patient_phone record
                          description: The resource's current CDM state, as projected
                            by canonical_v0_patient_phones_v01. Generated from the
                            vendored CDM DDL, so it cannot fall behind the columns
                            the view returns.
                          type: object
                          required:
                          - id
                          properties:
                            id:
                              type: integer
                            patient_id:
                              type: integer
                              nullable: true
                            phone_type:
                              type: string
                              nullable: true
                            phone_number:
                              type: string
                              nullable: true
                            country_code:
                              type: string
                              nullable: true
                            preferred_at:
                              type: string
                              format: date-time
                              nullable: true
                            source_system:
                              type: string
                              nullable: true
                            deleted:
                              type: string
                              format: date-time
                              description: Soft-delete timestamp; null when the record
                                is live
                              nullable: true
                            created_at:
                              type: string
                              format: date-time
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
                      patient_external_identifiers:
                        type: array
                        items:
                          title: canonical.v0.patient_external_identifier record
                          description: The resource's current CDM state, as projected
                            by canonical_v0_patient_external_identifiers_v01. Generated
                            from the vendored CDM DDL, so it cannot fall behind the
                            columns the view returns.
                          type: object
                          required:
                          - id
                          properties:
                            id:
                              type: integer
                            patient_id:
                              type: integer
                              nullable: true
                            identifier_type:
                              type: string
                              nullable: true
                            identifier_value:
                              type: string
                              nullable: true
                            issuing_jurisdiction:
                              type: string
                              nullable: true
                            valid_from:
                              type: string
                              format: date
                              nullable: true
                            valid_to:
                              type: string
                              format: date
                              nullable: true
                            source_system:
                              type: string
                              nullable: true
                            deleted:
                              type: string
                              format: date-time
                              description: Soft-delete timestamp; null when the record
                                is live
                              nullable: true
                            created_at:
                              type: string
                              format: date-time
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
                            primary:
                              type: boolean
                              description: Whether this is the patient's primary identifier.
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
    post:
      summary: Create a patient
      tags:
      - Patients
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '201':
          description: the created patient in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient record
                description: The resource's current CDM state, as projected by canonical_v0_patients_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  patient_identity_management_id:
                    type: string
                    nullable: true
                  regulatory_reference_number:
                    type: string
                    nullable: true
                  middle_name:
                    type: string
                    nullable: true
                  preferred_name:
                    type: string
                    nullable: true
                  full_legal_name:
                    type: string
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  sex_assigned_at_birth:
                    type: string
                    nullable: true
                    enum:
                    - not_specified
                    - female
                    - male
                  gender_identity:
                    type: string
                    nullable: true
                  pronouns:
                    type: string
                    nullable: true
                  ethnicity:
                    type: string
                    nullable: true
                  fathers_ethnicity:
                    type: string
                    nullable: true
                  mothers_ethnicity:
                    type: string
                    nullable: true
                  country_of_birth:
                    type: string
                    nullable: true
                  town_or_city_of_birth:
                    type: string
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                    description: ISO 3166-1 alpha-2 country code, uppercase (for example
                      AE, GB, IN)
                  religion:
                    type: string
                    nullable: true
                    enum:
                    - buddhist
                    - christian
                    - hindu
                    - jewish
                    - muslim
                    - sikh
                    - other
                    - no_religion
                    - not_disclosed
                  preferred_language:
                    type: string
                    nullable: true
                    description: 'ISO 639-1 two-letter language code, lowercase (for
                      example en, ro, ar). A full BCP 47 tag is narrowed to its language
                      subtag, so en-GB records as en. Also accepted, for languages
                      ISO 639-1 cannot express: yue, ckb, prs.'
                  marital_status:
                    type: string
                    nullable: true
                    enum:
                    - single
                    - married
                    - separated
                    - divorced
                    - widowed
                    - never_married
                    - in_civil_partnership
                    - separated_still_married
                    - separated_still_civil_partnership
                    - dissolved_civil_partnership
                    - surviving_partner
                    - not_disclosed
                    - cohabiting
                    - in_relationship
                  blood_group:
                    type: string
                    nullable: true
                  rhesus_factor:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_donor:
                    type: boolean
                    nullable: true
                  is_deceased:
                    type: boolean
                    nullable: true
                  date_of_death:
                    type: string
                    format: date
                    nullable: true
                  is_test_patient:
                    type: boolean
                    nullable: true
                  primary_user_id:
                    type: integer
                    nullable: true
                  brand_id:
                    type: integer
                    nullable: true
                  fund_source_id:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  initial_contact_at:
                    type: string
                    format: date-time
                    nullable: true
                  first_seen_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_last_sent_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_accepted_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_app_connected:
                    type: boolean
                    nullable: true
                  registration_status:
                    type: string
                    nullable: true
                  registration_completion_percentage:
                    type: integer
                    nullable: true
                  care_stage:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_portal_connected:
                    type: boolean
                    description: Whether the patient is connected to the patient portal
                      or app. Read-only.
        '422':
          description: invalid patient attributes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Integrator-assigned identifier, unique per account
                    and resource type. Omit to preserve; null clears it.
                first_name:
                  type: string
                middle_name:
                  type: string
                last_name:
                  type: string
                email:
                  type: string
                date_of_birth:
                  type: string
                  format: date
                  description: ISO8601 date — maps to core birthday
                sex_assigned_at_birth:
                  type: string
                  enum:
                  - not_specified
                  - female
                  - male
                gender_identity:
                  type: string
                  nullable: true
                  description: Free text for how the patient identifies. Distinct
                    from sex_assigned_at_birth. Omit to preserve; null clears.
                marital_status:
                  type: string
                  enum:
                  - single
                  - married
                  - separated
                  - divorced
                  - widowed
                  - never_married
                  - in_civil_partnership
                  - separated_still_married
                  - separated_still_civil_partnership
                  - dissolved_civil_partnership
                  - surviving_partner
                  - not_disclosed
                  - cohabiting
                  - in_relationship
                ethnicity:
                  type: string
                nationality:
                  type: string
                  nullable: true
                  description: ISO 3166-1 alpha-2 country code, uppercase (for example
                    AE, GB, IN). Omit to preserve; null clears.
                religion:
                  type: string
                  nullable: true
                  enum:
                  - buddhist
                  - christian
                  - hindu
                  - jewish
                  - muslim
                  - sikh
                  - other
                  - no_religion
                  - not_disclosed
                  description: Omit to preserve; null clears.
                brand_id:
                  type: integer
                  nullable: true
                  description: A brand in the patient's account. Omit to preserve;
                    null clears the patient's own brand, after which brand_id reads
                    back as their clinic's brand, if it has one.
                preferred_language:
                  type: string
                  description: 'ISO 639-1 two-letter language code, lowercase (for
                    example en, ro, ar). A full BCP 47 tag is narrowed to its language
                    subtag, so en-GB records as en. Also accepted, for languages ISO
                    639-1 cannot express: yue, ckb, prs.'
                address_line_1:
                  type: string
                address_line_2:
                  type: string
                town_or_city:
                  type: string
                state_or_province:
                  type: string
                postcode:
                  type: string
                country:
                  type: string
                  description: the address country, not a phone dialling code
                patient_identity_management_id:
                  type: string
                  description: the identity-management id; create only, rejected on
                    update
                clinic_ids:
                  type: array
                  items:
                    type: integer
                  description: assigns the patient to these clinics; create only,
                    rejected on update
  "/api/v2/patients/{id}":
    get:
      summary: Show a patient
      tags:
      - Patients
      security:
      - oauth2:
        - patients:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: include
        in: query
        required: false
        description: 'Child resources to return under top-level `included`: `patient_phones`,
          `patient_external_identifiers`, or both, comma separated. Join them to their
          patient on `patient_id`. An unknown value is 400. Show wraps the record
          in `{ data, included }` when this is present; without it the body is unchanged.
          A misspelled `includes=` (plural) is ignored.'
        schema:
          type: string
      responses:
        '200':
          description: the patient in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient record
                description: The resource's current CDM state, as projected by canonical_v0_patients_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  patient_identity_management_id:
                    type: string
                    nullable: true
                  regulatory_reference_number:
                    type: string
                    nullable: true
                  middle_name:
                    type: string
                    nullable: true
                  preferred_name:
                    type: string
                    nullable: true
                  full_legal_name:
                    type: string
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  sex_assigned_at_birth:
                    type: string
                    nullable: true
                    enum:
                    - not_specified
                    - female
                    - male
                  gender_identity:
                    type: string
                    nullable: true
                  pronouns:
                    type: string
                    nullable: true
                  ethnicity:
                    type: string
                    nullable: true
                  fathers_ethnicity:
                    type: string
                    nullable: true
                  mothers_ethnicity:
                    type: string
                    nullable: true
                  country_of_birth:
                    type: string
                    nullable: true
                  town_or_city_of_birth:
                    type: string
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                    description: ISO 3166-1 alpha-2 country code, uppercase (for example
                      AE, GB, IN)
                  religion:
                    type: string
                    nullable: true
                    enum:
                    - buddhist
                    - christian
                    - hindu
                    - jewish
                    - muslim
                    - sikh
                    - other
                    - no_religion
                    - not_disclosed
                  preferred_language:
                    type: string
                    nullable: true
                    description: 'ISO 639-1 two-letter language code, lowercase (for
                      example en, ro, ar). A full BCP 47 tag is narrowed to its language
                      subtag, so en-GB records as en. Also accepted, for languages
                      ISO 639-1 cannot express: yue, ckb, prs.'
                  marital_status:
                    type: string
                    nullable: true
                    enum:
                    - single
                    - married
                    - separated
                    - divorced
                    - widowed
                    - never_married
                    - in_civil_partnership
                    - separated_still_married
                    - separated_still_civil_partnership
                    - dissolved_civil_partnership
                    - surviving_partner
                    - not_disclosed
                    - cohabiting
                    - in_relationship
                  blood_group:
                    type: string
                    nullable: true
                  rhesus_factor:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_donor:
                    type: boolean
                    nullable: true
                  is_deceased:
                    type: boolean
                    nullable: true
                  date_of_death:
                    type: string
                    format: date
                    nullable: true
                  is_test_patient:
                    type: boolean
                    nullable: true
                  primary_user_id:
                    type: integer
                    nullable: true
                  brand_id:
                    type: integer
                    nullable: true
                  fund_source_id:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  initial_contact_at:
                    type: string
                    format: date-time
                    nullable: true
                  first_seen_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_last_sent_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_accepted_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_app_connected:
                    type: boolean
                    nullable: true
                  registration_status:
                    type: string
                    nullable: true
                  registration_completion_percentage:
                    type: integer
                    nullable: true
                  care_stage:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_portal_connected:
                    type: boolean
                    description: Whether the patient is connected to the patient portal
                      or app. Read-only.
        '404':
          description: no such patient in the principal's scope
    patch:
      summary: Update a patient
      tags:
      - Patients
      security:
      - oauth2:
        - patients:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated patient in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.patient record
                description: The resource's current CDM state, as projected by canonical_v0_patients_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  patient_identity_management_id:
                    type: string
                    nullable: true
                  regulatory_reference_number:
                    type: string
                    nullable: true
                  middle_name:
                    type: string
                    nullable: true
                  preferred_name:
                    type: string
                    nullable: true
                  full_legal_name:
                    type: string
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  sex_assigned_at_birth:
                    type: string
                    nullable: true
                    enum:
                    - not_specified
                    - female
                    - male
                  gender_identity:
                    type: string
                    nullable: true
                  pronouns:
                    type: string
                    nullable: true
                  ethnicity:
                    type: string
                    nullable: true
                  fathers_ethnicity:
                    type: string
                    nullable: true
                  mothers_ethnicity:
                    type: string
                    nullable: true
                  country_of_birth:
                    type: string
                    nullable: true
                  town_or_city_of_birth:
                    type: string
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                    description: ISO 3166-1 alpha-2 country code, uppercase (for example
                      AE, GB, IN)
                  religion:
                    type: string
                    nullable: true
                    enum:
                    - buddhist
                    - christian
                    - hindu
                    - jewish
                    - muslim
                    - sikh
                    - other
                    - no_religion
                    - not_disclosed
                  preferred_language:
                    type: string
                    nullable: true
                    description: 'ISO 639-1 two-letter language code, lowercase (for
                      example en, ro, ar). A full BCP 47 tag is narrowed to its language
                      subtag, so en-GB records as en. Also accepted, for languages
                      ISO 639-1 cannot express: yue, ckb, prs.'
                  marital_status:
                    type: string
                    nullable: true
                    enum:
                    - single
                    - married
                    - separated
                    - divorced
                    - widowed
                    - never_married
                    - in_civil_partnership
                    - separated_still_married
                    - separated_still_civil_partnership
                    - dissolved_civil_partnership
                    - surviving_partner
                    - not_disclosed
                    - cohabiting
                    - in_relationship
                  blood_group:
                    type: string
                    nullable: true
                  rhesus_factor:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_donor:
                    type: boolean
                    nullable: true
                  is_deceased:
                    type: boolean
                    nullable: true
                  date_of_death:
                    type: string
                    format: date
                    nullable: true
                  is_test_patient:
                    type: boolean
                    nullable: true
                  primary_user_id:
                    type: integer
                    nullable: true
                  brand_id:
                    type: integer
                    nullable: true
                  fund_source_id:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  initial_contact_at:
                    type: string
                    format: date-time
                    nullable: true
                  first_seen_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_last_sent_at:
                    type: string
                    format: date-time
                    nullable: true
                  app_invitation_accepted_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_app_connected:
                    type: boolean
                    nullable: true
                  registration_status:
                    type: string
                    nullable: true
                  registration_completion_percentage:
                    type: integer
                    nullable: true
                  care_stage:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  is_portal_connected:
                    type: boolean
                    description: Whether the patient is connected to the patient portal
                      or app. Read-only.
        '422':
          description: invalid patient attributes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Integrator-assigned identifier, unique per account
                    and resource type. Omit to preserve; null clears it.
                first_name:
                  type: string
                middle_name:
                  type: string
                last_name:
                  type: string
                email:
                  type: string
                date_of_birth:
                  type: string
                  format: date
                  description: ISO8601 date — maps to core birthday
                sex_assigned_at_birth:
                  type: string
                  enum:
                  - not_specified
                  - female
                  - male
                gender_identity:
                  type: string
                  nullable: true
                  description: Free text for how the patient identifies. Distinct
                    from sex_assigned_at_birth. Omit to preserve; null clears.
                marital_status:
                  type: string
                  enum:
                  - single
                  - married
                  - separated
                  - divorced
                  - widowed
                  - never_married
                  - in_civil_partnership
                  - separated_still_married
                  - separated_still_civil_partnership
                  - dissolved_civil_partnership
                  - surviving_partner
                  - not_disclosed
                  - cohabiting
                  - in_relationship
                ethnicity:
                  type: string
                nationality:
                  type: string
                  nullable: true
                  description: ISO 3166-1 alpha-2 country code, uppercase (for example
                    AE, GB, IN). Omit to preserve; null clears.
                religion:
                  type: string
                  nullable: true
                  enum:
                  - buddhist
                  - christian
                  - hindu
                  - jewish
                  - muslim
                  - sikh
                  - other
                  - no_religion
                  - not_disclosed
                  description: Omit to preserve; null clears.
                brand_id:
                  type: integer
                  nullable: true
                  description: A brand in the patient's account. Omit to preserve;
                    null clears the patient's own brand, after which brand_id reads
                    back as their clinic's brand, if it has one.
                preferred_language:
                  type: string
                  description: 'ISO 639-1 two-letter language code, lowercase (for
                    example en, ro, ar). A full BCP 47 tag is narrowed to its language
                    subtag, so en-GB records as en. Also accepted, for languages ISO
                    639-1 cannot express: yue, ckb, prs.'
                address_line_1:
                  type: string
                address_line_2:
                  type: string
                town_or_city:
                  type: string
                state_or_province:
                  type: string
                postcode:
                  type: string
                country:
                  type: string
                  description: the address country, not a phone dialling code
  "/api/v2/rooms":
    get:
      summary: List rooms
      tags:
      - Rooms
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the principal's bookable rooms, paginated in the { data, meta
            } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.room record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_rooms_v01. Generated from the vendored CDM
                        DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        location_id:
                          type: integer
                          nullable: true
                          description: The legacy clinic if set; otherwise the clinic
                            on the lowest-ID room assignment, or null if none.
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/rooms/{id}":
    get:
      summary: Show a room
      tags:
      - Rooms
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the room in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.room record
                description: The resource's current CDM state, as projected by canonical_v0_rooms_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                    description: The legacy clinic if set; otherwise the clinic on
                      the lowest-ID room assignment, or null if none.
                  is_active:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such room in the principal's scope
  "/api/v2/scheduler/calendars":
    get:
      summary: List calendars
      tags:
      - Scheduler calendars
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the principal's calendars, paginated in the { data, meta }
            envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.calendar record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_calendars_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/scheduler/calendars/{id}":
    get:
      summary: Show a calendar
      tags:
      - Scheduler calendars
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the calendar in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.calendar record
                description: The resource's current CDM state, as projected by canonical_v0_calendars_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such calendar in the principal's scope
  "/api/v2/scheduler/event_statuses":
    get:
      summary: List scheduler event statuses
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      responses:
        '200':
          description: the principal's scheduler event statuses, paginated in the
            { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.scheduler_event_status record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_scheduler_event_statuses_v01. Generated from
                        the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        external_identifier:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                          description: Whether the status can still be applied to
                            an appointment. A deactivated status stays on any appointment
                            already holding it
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: 'Soft-delete timestamp. Always null: event
                            statuses are deactivated, not deleted'
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
    post:
      summary: Create a scheduler event status
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '201':
          description: the created scheduler event status in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_status record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_statuses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                    description: Whether the status can still be applied to an appointment.
                      A deactivated status stays on any appointment already holding
                      it
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: 'Soft-delete timestamp. Always null: event statuses
                      are deactivated, not deleted'
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid — name already taken
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                is_active:
                  type: boolean
                  description: Whether staff can apply the status straight away. Defaults
                    to false; afterwards use the activate / deactivate endpoints
  "/api/v2/scheduler/event_statuses/{id}":
    get:
      summary: Show a scheduler event status
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the scheduler event status in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_status record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_statuses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                    description: Whether the status can still be applied to an appointment.
                      A deactivated status stays on any appointment already holding
                      it
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: 'Soft-delete timestamp. Always null: event statuses
                      are deactivated, not deleted'
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such scheduler event status in the principal's scope
    patch:
      summary: Update a scheduler event status
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated scheduler event status in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_status record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_statuses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                    description: Whether the status can still be applied to an appointment.
                      A deactivated status stays on any appointment already holding
                      it
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: 'Soft-delete timestamp. Always null: event statuses
                      are deactivated, not deleted'
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Custom statuses only. A system-wide status cannot be
                    renamed
                external_identifier:
                  type: string
                  nullable: true
                  description: Unique per account and resource type, and settable
                    on system-wide statuses too. Omit to preserve; null clears it.
  "/api/v2/scheduler/event_statuses/{id}/activate":
    post:
      summary: Activate a scheduler event status
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the activated scheduler event status in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_status record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_statuses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                    description: Whether the status can still be applied to an appointment.
                      A deactivated status stays on any appointment already holding
                      it
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: 'Soft-delete timestamp. Always null: event statuses
                      are deactivated, not deleted'
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
  "/api/v2/scheduler/event_statuses/{id}/deactivate":
    post:
      summary: Deactivate a scheduler event status
      tags:
      - Scheduler event statuses
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the deactivated scheduler event status in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_status record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_statuses_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                    description: Whether the status can still be applied to an appointment.
                      A deactivated status stays on any appointment already holding
                      it
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: 'Soft-delete timestamp. Always null: event statuses
                      are deactivated, not deleted'
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
  "/api/v2/scheduler/event_types":
    get:
      summary: List scheduler event types
      tags:
      - Scheduler event types
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      responses:
        '200':
          description: the principal's bookable event types, paginated in the { data,
            meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.scheduler_event_type record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_scheduler_event_types_v01. Generated from
                        the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        code:
                          type: string
                          nullable: true
                        name:
                          type: string
                          nullable: true
                        external_identifier:
                          type: string
                          nullable: true
                        category:
                          type: string
                          nullable: true
                        description:
                          type: string
                          nullable: true
                        duration:
                          type: integer
                          nullable: true
                        is_physical:
                          type: boolean
                          nullable: true
                        is_phone_call:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/scheduler/event_types/{id}":
    patch:
      summary: Update an event type's external identifier
      tags:
      - Scheduler event types
      security:
      - oauth2: []
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated event type in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_type record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_types_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  code:
                    type: string
                    nullable: true
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  category:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  duration:
                    type: integer
                    nullable: true
                  is_physical:
                    type: boolean
                    nullable: true
                  is_phone_call:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid external identifier
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Unique per account and resource type. Omit to preserve;
                    null clears it. Requires scheduler:write.
    get:
      summary: Show a scheduler event type
      tags:
      - Scheduler event types
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the scheduler event type in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_type record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_types_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  code:
                    type: string
                    nullable: true
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  category:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  duration:
                    type: integer
                    nullable: true
                  is_physical:
                    type: boolean
                    nullable: true
                  is_phone_call:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such event type in the principal's scope — also the case
            for a discarded one
  "/api/v2/scheduler/events/{event_id}/join_link":
    get:
      summary: Patient and guest join links for a video appointment
      tags:
      - Scheduler events
      security:
      - oauth2: []
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the patient and guest links and when the call closes
          content:
            application/json:
              schema:
                type: object
                required:
                - patient_url
                - guest_url
                - expires_at
                properties:
                  patient_url:
                    type: string
                    description: Waiting-room URL invitation emails use
                  guest_url:
                    type: string
                    description: URL that opens the call directly
                  expires_at:
                    type: string
                    format: date-time
                    description: When the call closes, one hour after the appointment
                      ends
        '422':
          description: not a video appointment, or the call has closed
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          description: no such event in the principal's scope
  "/api/v2/scheduler/events/{event_id}/resources":
    get:
      summary: List an event's resources
      tags:
      - Scheduler event resources
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: the event's resources, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.scheduler_event_resource record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_scheduler_event_resources_v01. Generated from
                        the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      - scheduler_event_id
                      properties:
                        id:
                          type: integer
                        scheduler_event_id:
                          type: integer
                          nullable: true
                        user_id:
                          type: integer
                          nullable: true
                        team_id:
                          type: integer
                          nullable: true
                        room_id:
                          type: integer
                          nullable: true
                        calendar_id:
                          type: integer
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no such event in the principal's scope
  "/api/v2/scheduler/events/{event_id}/resources/{id}":
    get:
      summary: Show an event resource
      tags:
      - Scheduler event resources
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: integer
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the event resource in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event_resource record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_event_resources_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - scheduler_event_id
                properties:
                  id:
                    type: integer
                  scheduler_event_id:
                    type: integer
                    nullable: true
                  user_id:
                    type: integer
                    nullable: true
                  team_id:
                    type: integer
                    nullable: true
                  room_id:
                    type: integer
                    nullable: true
                  calendar_id:
                    type: integer
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such resource for this event
  "/api/v2/scheduler/events":
    get:
      summary: List scheduler events
      tags:
      - Scheduler events
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[start_at_gteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Starts at or after (ISO8601)
      - name: q[start_at_lteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Starts at or before (ISO8601)
      - name: q[end_at_gteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Ends at or after (ISO8601)
      - name: q[end_at_lteq]
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Ends at or before (ISO8601)
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Child resources to return under top-level `included`. Currently
          `scheduler_event_resources`. An unknown value is 400. Show and create wrap
          the record in `{ data, included }` when this is present; without it the
          body is unchanged. A misspelled `includes=` (plural) is ignored.
        schema:
          type: string
      responses:
        '200':
          description: the principal's scheduler events (matching the q filters when
            given), paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.scheduler_event record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_scheduler_events_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        external_identifier:
                          type: string
                          nullable: true
                        patient_id:
                          type: integer
                          nullable: true
                        scheduler_event_type_id:
                          type: integer
                          nullable: true
                        event_type:
                          type: string
                          nullable: true
                        title:
                          type: string
                          nullable: true
                        start_at:
                          type: string
                          format: date-time
                          nullable: true
                        end_at:
                          type: string
                          format: date-time
                          nullable: true
                        all_day:
                          type: boolean
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        appointment_status:
                          type: string
                          nullable: true
                        scheduler_event_status_id:
                          type: integer
                          nullable: true
                        location_id:
                          type: integer
                          nullable: true
                        meeting_type:
                          type: string
                          nullable: true
                          enum:
                          - in_person
                          - virtual
                          - phone_call
                          - external
                        booked_online_at:
                          type: string
                          format: date-time
                          nullable: true
                        notes:
                          type: string
                          nullable: true
                        internal_notes:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  included:
                    type: object
                    properties:
                      scheduler_event_resources:
                        type: array
                        items:
                          title: canonical.v0.scheduler_event_resource record
                          description: The resource's current CDM state, as projected
                            by canonical_v0_scheduler_event_resources_v01. Generated
                            from the vendored CDM DDL, so it cannot fall behind the
                            columns the view returns.
                          type: object
                          required:
                          - id
                          - scheduler_event_id
                          properties:
                            id:
                              type: integer
                            scheduler_event_id:
                              type: integer
                              nullable: true
                            user_id:
                              type: integer
                              nullable: true
                            team_id:
                              type: integer
                              nullable: true
                            room_id:
                              type: integer
                              nullable: true
                            calendar_id:
                              type: integer
                              nullable: true
                            source_system:
                              type: string
                              nullable: true
                            deleted:
                              type: string
                              format: date-time
                              description: Soft-delete timestamp; null when the record
                                is live
                              nullable: true
                            created_at:
                              type: string
                              format: date-time
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
    post:
      summary: Book an appointment
      tags:
      - Scheduler events
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: include
        in: query
        required: false
        description: Child resources to return under top-level `included`. Currently
          `scheduler_event_resources`. An unknown value is 400. Show and create wrap
          the record in `{ data, included }` when this is present; without it the
          body is unchanged. A misspelled `includes=` (plural) is ignored.
        schema:
          type: string
      responses:
        '201':
          description: the booked appointment in CDM shape (the slot payload plus
            a patient_id)
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_events_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  patient_id:
                    type: integer
                    nullable: true
                  scheduler_event_type_id:
                    type: integer
                    nullable: true
                  event_type:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  start_at:
                    type: string
                    format: date-time
                    nullable: true
                  end_at:
                    type: string
                    format: date-time
                    nullable: true
                  all_day:
                    type: boolean
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  appointment_status:
                    type: string
                    nullable: true
                  scheduler_event_status_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  meeting_type:
                    type: string
                    nullable: true
                    enum:
                    - in_person
                    - virtual
                    - phone_call
                    - external
                  booked_online_at:
                    type: string
                    format: date-time
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  internal_notes:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: the booking is invalid — here a chosen host is already booked
            in the interval, rejected unless allow_overlap is sent
        '403':
          description: a clinic-restricted client booking a patient outside its clinics,
            or into a location outside its list
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - patient_id
              - event_type_id
              - start_at
              - end_at
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Optional integrator-assigned identifier, unique per
                    account and resource type.
                patient_id:
                  type: integer
                  description: A clinic-restricted client may only book patients in
                    its clinics.
                event_type_id:
                  type: integer
                  description: CDM scheduler event type id; maps to an appointment
                    category
                start_at:
                  type: string
                  format: date-time
                  description: ISO8601 slot start
                end_at:
                  type: string
                  format: date-time
                  description: ISO8601 slot end
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: CDM user ids of the hosting staff
                team_ids:
                  type: array
                  items:
                    type: integer
                room_ids:
                  type: array
                  items:
                    type: integer
                title:
                  type: string
                  description: Optional. Omitted, null or blank uses the event type's
                    patient-facing name. Stored and returned, but the clinic app calendar
                    shows the appointment type name, and saving there overwrites the
                    stored title.
                notes:
                  type: string
                  description: 'Optional. Patient-facing: shown in the patient portal
                    and included in reminder emails.'
                internal_notes:
                  type: string
                  description: Optional. Staff-only in the wawa UI; the CDM still
                    projects it, so it reaches every subscribed webhook endpoint.
                location_id:
                  type: integer
                  description: Optional CDM location id (a clinic). Omitted or null
                    inherits the event type's clinic. Not required for in-person bookings.
                    A clinic-restricted client may only book into a location in its
                    own list, including one inherited from the event type, so it must
                    send one when the event type has no clinic.
                scheduler_event_status_id:
                  type: integer
                  description: Optional. Omitted leaves status unset. There is no
                    default BOOKED status; read ids from GET /scheduler/event_statuses.
                meeting_type:
                  type: string
                  enum:
                  - in_person
                  - virtual
                  - phone_call
                  - external
                  description: Appointment format. Defaults to the event type's configuration.
                allow_overlap:
                  type: boolean
                  description: Book even if a chosen user, team or room is already
                    booked in the interval. Does not waive a patient conflict. Defaults
                    to false.
                allow_patient_overlap:
                  type: boolean
                  description: Book even if the patient already has a kept appointment
                    in the interval. Does not waive a staff, team or room conflict.
                    Defaults to false.
                trigger_blueprints:
                  type: boolean
                  description: Apply the event type's active action-plan blueprint
                    to the patient. Defaults to false. No-op when the event type has
                    no active blueprint. Rejected on update.
  "/api/v2/scheduler/events/{id}":
    patch:
      summary: Update an appointment
      tags:
      - Scheduler events
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: include
        in: query
        required: false
        description: Child resources to return under top-level `included`. Currently
          `scheduler_event_resources`. An unknown value is 400. Show and create wrap
          the record in `{ data, included }` when this is present; without it the
          body is unchanged. A misspelled `includes=` (plural) is ignored.
        schema:
          type: string
      responses:
        '200':
          description: the updated appointment in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_events_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  patient_id:
                    type: integer
                    nullable: true
                  scheduler_event_type_id:
                    type: integer
                    nullable: true
                  event_type:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  start_at:
                    type: string
                    format: date-time
                    nullable: true
                  end_at:
                    type: string
                    format: date-time
                    nullable: true
                  all_day:
                    type: boolean
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  appointment_status:
                    type: string
                    nullable: true
                  scheduler_event_status_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  meeting_type:
                    type: string
                    nullable: true
                    enum:
                    - in_person
                    - virtual
                    - phone_call
                    - external
                  booked_online_at:
                    type: string
                    format: date-time
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  internal_notes:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid update; no fields are changed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Partial update of a patient appointment. Omitted fields
                are preserved. Supplied resource arrays replace that resource type;
                [] clears it. Meetings and blocked time are not supported. Requires
                scheduler:write.
              properties:
                patient_id:
                  type: integer
                event_type_id:
                  type: integer
                start_at:
                  type: string
                  format: date-time
                end_at:
                  type: string
                  format: date-time
                title:
                  type: string
                notes:
                  type: string
                  nullable: true
                internal_notes:
                  type: string
                  nullable: true
                location_id:
                  type: integer
                  nullable: true
                scheduler_event_status_id:
                  type: integer
                  nullable: true
                meeting_type:
                  type: string
                  nullable: true
                  enum:
                  - in_person
                  - virtual
                  - phone_call
                  - external
                  -
                  description: Null resets to virtual.
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: CDM User IDs, not account-user IDs.
                team_ids:
                  type: array
                  items:
                    type: integer
                room_ids:
                  type: array
                  items:
                    type: integer
                allow_overlap:
                  type: boolean
                  description: Override staff, team and room conflicts. Defaults to
                    false.
                allow_patient_overlap:
                  type: boolean
                  description: Override patient conflicts independently. Defaults
                    to false.
                external_identifier:
                  type: string
                  nullable: true
                  description: Unique per account and resource type. Omit to preserve;
                    null clears it.
    get:
      summary: Show a scheduler event
      tags:
      - Scheduler events
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: include
        in: query
        required: false
        description: Child resources to return under top-level `included`. Currently
          `scheduler_event_resources`. An unknown value is 400. Show and create wrap
          the record in `{ data, included }` when this is present; without it the
          body is unchanged. A misspelled `includes=` (plural) is ignored.
        schema:
          type: string
      responses:
        '200':
          description: the scheduler event in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_events_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  patient_id:
                    type: integer
                    nullable: true
                  scheduler_event_type_id:
                    type: integer
                    nullable: true
                  event_type:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  start_at:
                    type: string
                    format: date-time
                    nullable: true
                  end_at:
                    type: string
                    format: date-time
                    nullable: true
                  all_day:
                    type: boolean
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  appointment_status:
                    type: string
                    nullable: true
                  scheduler_event_status_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  meeting_type:
                    type: string
                    nullable: true
                    enum:
                    - in_person
                    - virtual
                    - phone_call
                    - external
                  booked_online_at:
                    type: string
                    format: date-time
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  internal_notes:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such scheduler event in the principal's scope
  "/api/v2/scheduler/events/{event_id}/status":
    patch:
      summary: Change a scheduler event's status
      tags:
      - Scheduler events
      security:
      - oauth2:
        - scheduler:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: event_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the scheduler event in CDM shape, with the new status
          content:
            application/json:
              schema:
                title: canonical.v0.scheduler_event record
                description: The resource's current CDM state, as projected by canonical_v0_scheduler_events_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  patient_id:
                    type: integer
                    nullable: true
                  scheduler_event_type_id:
                    type: integer
                    nullable: true
                  event_type:
                    type: string
                    nullable: true
                  title:
                    type: string
                    nullable: true
                  start_at:
                    type: string
                    format: date-time
                    nullable: true
                  end_at:
                    type: string
                    format: date-time
                    nullable: true
                  all_day:
                    type: boolean
                    nullable: true
                  status:
                    type: string
                    nullable: true
                  appointment_status:
                    type: string
                    nullable: true
                  scheduler_event_status_id:
                    type: integer
                    nullable: true
                  location_id:
                    type: integer
                    nullable: true
                  meeting_type:
                    type: string
                    nullable: true
                    enum:
                    - in_person
                    - virtual
                    - phone_call
                    - external
                  booked_online_at:
                    type: string
                    format: date-time
                    nullable: true
                  notes:
                    type: string
                    nullable: true
                  internal_notes:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: the scheduler event status id is not one of the principal's
            statuses
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - scheduler_event_status_id
              properties:
                scheduler_event_status_id:
                  type: integer
                  description: The CDM scheduler event status id
  "/api/v2/scheduler/slots":
    get:
      summary: List available slots
      tags:
      - Scheduler slots
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: event_type_id
        in: query
        required: false
        description: CDM scheduler event type id; maps to an appointment category
        schema:
          type: integer
      - name: location_id
        in: query
        required: false
        description: Clinic for the booking, defaulting to the event type's location.
          In-person slots require a location accepted by the host for the entire appointment.
          An unset working-location default accepts any clinic. Explicit remote intervals
          exclude in-person slots; explicit clinic intervals require that clinic.
          Team capacity is assigned to eligible members. Virtual and phone appointments
          do not require a location match.
        schema:
          type: integer
      - name: meeting_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - in_person
          - virtual
          - phone_call
          - external
        description: Overrides the event type's format for this search. `in_person`
          applies the working-location rules; `virtual`, `phone_call` and `external`
          do not. Omitted follows the event type (`is_physical`). An unknown value
          is a 400.
      - name: from
        in: query
        schema:
          type: string
          format: date
        required: false
        description: ISO8601 date — window start (defaults to today)
      - name: to
        in: query
        schema:
          type: string
          format: date
        required: false
        description: ISO8601 date — window end (capped at 30 days from start)
      - name: patient_id
        in: query
        required: false
        description: Excludes times the patient is already booked. A patient outside
          the client's clinics is a 404
        schema:
          type: integer
      - name: duration_minutes
        in: query
        schema:
          type: integer
          minimum: 1
        required: false
        description: Overrides the event type's duration; must be a positive integer.
          Invalid values return 400.
      - name: user_ids
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: When present, slots come from that user's matching schedule blocks
          and from matching blocks on their teams. When omitted with event_type_id
          and no room_ids, any user or team with a matching schedule block is its
          own slot, paired with a room if require_room=true. Repeated keys, a comma-separated
          list and user_ids[] are all accepted; present with no values is a 400
      - name: team_ids
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: When present without user_ids, slots come from those teams' matching
          schedule blocks
      - name: room_ids
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: Candidate room ids from GET /rooms. Alone, returns one room-only
          slot per available room. With user_ids or team_ids, returns one host-room
          pair per mutually available interval inside both resources' matching schedule
          blocks. Rooms are alternatives, not jointly required. For in-person searches
          with a location, only rooms assigned to that location are candidates. Unknown
          or cross-account room ids yield no slots. Mutually exclusive with require_room
          (including false); combining them is a 400. Room bookings, schedule conflicts
          and buffers are respected; room-only slots do not require staff.
      - name: require_room
        in: query
        required: false
        schema:
          type: boolean
        description: Use true to discover rooms automatically and return only host-room
          pairs with mutual availability. With user_ids or team_ids, pairs those hosts
          with candidate rooms; without either, searches all scheduled staff/teams.
          For in-person searches with a location, only rooms assigned to that location
          are candidates. Never returns roomless slots, including when no rooms are
          available. Each result carries one concrete room_id in room_ids. Use from
          the first search when a room is mandatory but staff are selected first.
          Omitted or false preserves staff/team-only lookup. Only true and false are
          accepted. Mutually exclusive with room_ids, even when false; combining them
          is a 400. This is a search option, not a booking field.
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: available slots ascending in the { data, meta } envelope; the
            first element is the first available slot, and each slot is one bookable
            set (POST it with a patient_id)
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - start_at
                      - end_at
                      - event_type_id
                      - user_ids
                      - team_ids
                      - room_ids
                      properties:
                        start_at:
                          type: string
                          format: date-time
                        end_at:
                          type: string
                          format: date-time
                        event_type_id:
                          type: integer
                          nullable: true
                        location_id:
                          type: integer
                          description: Booking location; included when specified or
                            defaulted from the event type
                        meeting_type:
                          type: string
                          enum:
                          - in_person
                          - virtual
                          - phone_call
                          - external
                          description: Included when the search passed `meeting_type`;
                            send it back when booking
                        user_ids:
                          type: array
                          items:
                            type: integer
                          description: CDM user ids of the hosting staff
                        team_ids:
                          type: array
                          items:
                            type: integer
                        room_ids:
                          type: array
                          items:
                            type: integer
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '400':
          description: invalid duration, invalid require_room boolean or mutually
            exclusive room selection parameters
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
        '404':
          description: no such event type or patient in the principal's scope
  "/api/v2/settings/cycle_protocols":
    get:
      summary: List cycle protocols
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: kept protocols, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cycle_protocol record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cycle_protocols_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - cycle_treatment_type_id
                      - protocol_name
                      properties:
                        id:
                          type: integer
                        cycle_treatment_type_id:
                          type: integer
                          nullable: true
                        protocol_name:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/settings/cycle_protocols/{id}":
    get:
      summary: Show a cycle protocol
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the protocol in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cycle_protocol record
                description: The resource's current CDM state, as projected by canonical_v0_cycle_protocols_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - cycle_treatment_type_id
                - protocol_name
                properties:
                  id:
                    type: integer
                  cycle_treatment_type_id:
                    type: integer
                    nullable: true
                  protocol_name:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such protocol in the principal's scope
  "/api/v2/settings/cycle_treatment_types":
    get:
      summary: List cycle treatment types
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      responses:
        '200':
          description: kept treatment types, paginated in the { data, meta } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.cycle_treatment_type record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_cycle_treatment_types_v01. Generated from
                        the vendored CDM DDL, so it cannot fall behind the columns
                        the view returns.
                      type: object
                      required:
                      - id
                      - treatment_name
                      properties:
                        id:
                          type: integer
                        treatment_name:
                          type: string
                          nullable: true
                        external_identifier:
                          type: string
                          nullable: true
                        primary_treatment_classification:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/settings/cycle_treatment_types/{id}":
    patch:
      summary: Update a cycle treatment type's external identifier
      tags:
      - Settings
      security:
      - oauth2:
        - settings:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated treatment type in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cycle_treatment_type record
                description: The resource's current CDM state, as projected by canonical_v0_cycle_treatment_types_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - treatment_name
                properties:
                  id:
                    type: integer
                  treatment_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  primary_treatment_classification:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid external identifier
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Unique per account and resource type. Omit to preserve;
                    null clears it. Requires settings:write.
    get:
      summary: Show a cycle treatment type
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the treatment type in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.cycle_treatment_type record
                description: The resource's current CDM state, as projected by canonical_v0_cycle_treatment_types_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - treatment_name
                properties:
                  id:
                    type: integer
                  treatment_name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  primary_treatment_classification:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such treatment type in the principal's scope
  "/api/v2/settings/fund_sources":
    get:
      summary: List fund sources
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      responses:
        '200':
          description: the principal's fund sources, paginated in the { data, meta
            } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.fund_source record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_fund_sources_v01. Generated from the vendored
                        CDM DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        external_identifier:
                          type: string
                          nullable: true
                        contact_name:
                          type: string
                          nullable: true
                        contact_email:
                          type: string
                          nullable: true
                        contact_phone_country_code:
                          type: string
                          nullable: true
                        contact_phone_number:
                          type: string
                          nullable: true
                        contact_address_line_1:
                          type: string
                          nullable: true
                        contact_address_line_2:
                          type: string
                          nullable: true
                        contact_town_or_city:
                          type: string
                          nullable: true
                        contact_region:
                          type: string
                          nullable: true
                        contact_postcode:
                          type: string
                          nullable: true
                        contact_country:
                          type: string
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp, set once the fund source
                            is deleted
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
    post:
      summary: Create a fund source
      tags:
      - Settings
      security:
      - oauth2:
        - settings:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      responses:
        '201':
          description: the created fund source in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.fund_source record
                description: The resource's current CDM state, as projected by canonical_v0_fund_sources_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  contact_name:
                    type: string
                    nullable: true
                  contact_email:
                    type: string
                    nullable: true
                  contact_phone_country_code:
                    type: string
                    nullable: true
                  contact_phone_number:
                    type: string
                    nullable: true
                  contact_address_line_1:
                    type: string
                    nullable: true
                  contact_address_line_2:
                    type: string
                    nullable: true
                  contact_town_or_city:
                    type: string
                    nullable: true
                  contact_region:
                    type: string
                    nullable: true
                  contact_postcode:
                    type: string
                    nullable: true
                  contact_country:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp, set once the fund source is
                      deleted
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid — no name
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                external_identifier:
                  type: string
                  nullable: true
                  description: Integrator-assigned identifier, unique per account
                    and resource type. Omit to preserve; null clears it.
  "/api/v2/settings/fund_sources/{id}":
    get:
      summary: Show a fund source
      tags:
      - Settings
      security:
      - oauth2:
        - settings:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the fund source in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.fund_source record
                description: The resource's current CDM state, as projected by canonical_v0_fund_sources_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  contact_name:
                    type: string
                    nullable: true
                  contact_email:
                    type: string
                    nullable: true
                  contact_phone_country_code:
                    type: string
                    nullable: true
                  contact_phone_number:
                    type: string
                    nullable: true
                  contact_address_line_1:
                    type: string
                    nullable: true
                  contact_address_line_2:
                    type: string
                    nullable: true
                  contact_town_or_city:
                    type: string
                    nullable: true
                  contact_region:
                    type: string
                    nullable: true
                  contact_postcode:
                    type: string
                    nullable: true
                  contact_country:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp, set once the fund source is
                      deleted
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such fund source in the principal's scope
    patch:
      summary: Update a fund source
      tags:
      - Settings
      security:
      - oauth2:
        - settings:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated fund source in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.fund_source record
                description: The resource's current CDM state, as projected by canonical_v0_fund_sources_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  contact_name:
                    type: string
                    nullable: true
                  contact_email:
                    type: string
                    nullable: true
                  contact_phone_country_code:
                    type: string
                    nullable: true
                  contact_phone_number:
                    type: string
                    nullable: true
                  contact_address_line_1:
                    type: string
                    nullable: true
                  contact_address_line_2:
                    type: string
                    nullable: true
                  contact_town_or_city:
                    type: string
                    nullable: true
                  contact_region:
                    type: string
                    nullable: true
                  contact_postcode:
                    type: string
                    nullable: true
                  contact_country:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp, set once the fund source is
                      deleted
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                external_identifier:
                  type: string
                  nullable: true
                  description: Integrator-assigned identifier, unique per account
                    and resource type. Omit to preserve; null clears it.
    delete:
      summary: Delete a fund source
      tags:
      - Settings
      security:
      - oauth2:
        - settings:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the deleted fund source in its final CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.fund_source record
                description: The resource's current CDM state, as projected by canonical_v0_fund_sources_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  external_identifier:
                    type: string
                    nullable: true
                  contact_name:
                    type: string
                    nullable: true
                  contact_email:
                    type: string
                    nullable: true
                  contact_phone_country_code:
                    type: string
                    nullable: true
                  contact_phone_number:
                    type: string
                    nullable: true
                  contact_address_line_1:
                    type: string
                    nullable: true
                  contact_address_line_2:
                    type: string
                    nullable: true
                  contact_town_or_city:
                    type: string
                    nullable: true
                  contact_region:
                    type: string
                    nullable: true
                  contact_postcode:
                    type: string
                    nullable: true
                  contact_country:
                    type: string
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp, set once the fund source is
                      deleted
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
  "/api/v2/teams":
    get:
      summary: List teams
      tags:
      - Teams
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      responses:
        '200':
          description: the principal's bookable teams, paginated in the { data, meta
            } envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.team record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_teams_v01. Generated from the vendored CDM
                        DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/teams/{id}":
    get:
      summary: Show a team
      tags:
      - Teams
      security:
      - oauth2:
        - scheduler:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the team in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.team record
                description: The resource's current CDM state, as projected by canonical_v0_teams_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such team in the principal's scope
  "/api/v2/users":
    get:
      summary: List staff members
      tags:
      - Users
      security:
      - oauth2:
        - users:read
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number
        schema:
          type: integer
      - name: items
        in: query
        required: false
        description: Page size (capped at 100)
        schema:
          type: integer
      - name: q[search]
        in: query
        required: false
        description: 'Free-text query: name or email'
        schema:
          type: string
      - name: q[first_name_cont]
        in: query
        required: false
        description: First name contains
        schema:
          type: string
      - name: q[last_name_cont]
        in: query
        required: false
        description: Last name contains
        schema:
          type: string
      - name: q[external_identifier_eq]
        in: query
        required: false
        description: Exact, case-sensitive external identifier
        schema:
          type: string
      responses:
        '200':
          description: the account's staff members (matching the q filters when given),
            paginated in the { data, meta } envelope; ids are the CDM user ids the
            slot and booking endpoints accept
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.user record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_users_v01. Generated from the vendored CDM
                        DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        external_identifier:
                          type: string
                          nullable: true
                        first_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                          nullable: true
                        gender:
                          type: string
                          nullable: true
                        email:
                          type: string
                          nullable: true
                        work_phone_country_code:
                          type: string
                          nullable: true
                        work_phone_number:
                          type: string
                          nullable: true
                        role:
                          type: string
                          nullable: true
                        specialty:
                          type: string
                          nullable: true
                        staff_type:
                          type: string
                          nullable: true
                        provider_number:
                          type: string
                          nullable: true
                        address_line_1:
                          type: string
                          nullable: true
                        address_line_2:
                          type: string
                          nullable: true
                        town_or_city:
                          type: string
                          nullable: true
                        state_or_province:
                          type: string
                          nullable: true
                        postcode:
                          type: string
                          nullable: true
                        country:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
  "/api/v2/locations/{location_id}/users":
    get:
      summary: List a location's staff members
      tags:
      - Locations
      security:
      - oauth2:
        - users:read
      parameters:
      - name: location_id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: items
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: assigned staff with active memberships in the client's account
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      title: canonical.v0.user record
                      description: The resource's current CDM state, as projected
                        by canonical_v0_users_v01. Generated from the vendored CDM
                        DDL, so it cannot fall behind the columns the view returns.
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                        external_identifier:
                          type: string
                          nullable: true
                        first_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                          nullable: true
                        gender:
                          type: string
                          nullable: true
                        email:
                          type: string
                          nullable: true
                        work_phone_country_code:
                          type: string
                          nullable: true
                        work_phone_number:
                          type: string
                          nullable: true
                        role:
                          type: string
                          nullable: true
                        specialty:
                          type: string
                          nullable: true
                        staff_type:
                          type: string
                          nullable: true
                        provider_number:
                          type: string
                          nullable: true
                        address_line_1:
                          type: string
                          nullable: true
                        address_line_2:
                          type: string
                          nullable: true
                        town_or_city:
                          type: string
                          nullable: true
                        state_or_province:
                          type: string
                          nullable: true
                        postcode:
                          type: string
                          nullable: true
                        country:
                          type: string
                          nullable: true
                        is_active:
                          type: boolean
                          nullable: true
                        source_system:
                          type: string
                          nullable: true
                        deleted:
                          type: string
                          format: date-time
                          description: Soft-delete timestamp; null when the record
                            is live
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                          nullable: true
                        updated_at:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    type: object
                    required:
                    - page
                    - items
                    - count
                    - pages
                    properties:
                      page:
                        type: integer
                      items:
                        type: integer
                      count:
                        type: integer
                      pages:
                        type: integer
                      next:
                        type: integer
                        nullable: true
                      prev:
                        type: integer
                        nullable: true
        '404':
          description: no kept location in the client's account and clinic scope
        '403':
          description: users:read is required; scheduler:read alone is insufficient
  "/api/v2/users/{id}":
    patch:
      summary: Update a staff member's external identifier
      tags:
      - Users
      security:
      - oauth2:
        - users:write
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the updated staff member in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.user record
                description: The resource's current CDM state, as projected by canonical_v0_users_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  gender:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  work_phone_country_code:
                    type: string
                    nullable: true
                  work_phone_number:
                    type: string
                    nullable: true
                  role:
                    type: string
                    nullable: true
                  specialty:
                    type: string
                    nullable: true
                  staff_type:
                    type: string
                    nullable: true
                  provider_number:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '422':
          description: invalid external identifier
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_identifier:
                  type: string
                  nullable: true
                  description: Unique per account and resource type. Omit to preserve;
                    null clears it. Requires users:write.
    get:
      summary: Show a staff member
      tags:
      - Users
      security:
      - oauth2:
        - users:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: the staff member in CDM shape
          content:
            application/json:
              schema:
                title: canonical.v0.user record
                description: The resource's current CDM state, as projected by canonical_v0_users_v01.
                  Generated from the vendored CDM DDL, so it cannot fall behind the
                  columns the view returns.
                type: object
                required:
                - id
                properties:
                  id:
                    type: integer
                  external_identifier:
                    type: string
                    nullable: true
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  gender:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                  work_phone_country_code:
                    type: string
                    nullable: true
                  work_phone_number:
                    type: string
                    nullable: true
                  role:
                    type: string
                    nullable: true
                  specialty:
                    type: string
                    nullable: true
                  staff_type:
                    type: string
                    nullable: true
                  provider_number:
                    type: string
                    nullable: true
                  address_line_1:
                    type: string
                    nullable: true
                  address_line_2:
                    type: string
                    nullable: true
                  town_or_city:
                    type: string
                    nullable: true
                  state_or_province:
                    type: string
                    nullable: true
                  postcode:
                    type: string
                    nullable: true
                  country:
                    type: string
                    nullable: true
                  is_active:
                    type: boolean
                    nullable: true
                  source_system:
                    type: string
                    nullable: true
                  deleted:
                    type: string
                    format: date-time
                    description: Soft-delete timestamp; null when the record is live
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: no such staff member in the principal's account
  "/api/v2/webhook_deliveries/{delivery_id}/outcomes":
    post:
      summary: Report the processing outcome of a webhook delivery
      tags:
      - Webhook outcomes
      security:
      - oauth2:
        - webhook_outcomes:write
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The Wawa-Delivery-Id from the original request
      responses:
        '204':
          description: recorded, including an identical repeat
        '403':
          description: token lacks the reporting scope
        '404':
          description: delivery is unknown or outside this client's assignment
        '409':
          description: this sequence already has a different report
        '422':
          description: invalid report
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sequence
              - status
              additionalProperties: false
              properties:
                sequence:
                  type: integer
                  minimum: 1
                  maximum: 2147483647
                  description: Increasing report number within this delivery. Reuse
                    on retry.
                status:
                  type: string
                  enum:
                  - accepted
                  - failed
                  - skipped
                  - unknown
                reason_code:
                  type: string
                  pattern: "^[a-zA-Z0-9_.-]{1,80}$"
                  description: Required for failed, skipped or unknown. Exclude patient
                    data.
                provider_reference:
                  type: string
                  maxLength: 128
                  description: An opaque submission reference without patient data
                sent:
                  type: boolean
                  description: Required for failed. Whether the provider sent the
                    submission downstream.
        required: true
servers:
- url: "{defaultHost}"
  variables:
    defaultHost:
      default: https://clinic.wawafertility.com
