openapi: 3.1.0
info:
  title: External API
  x-logo:
    url: "https://storage.googleapis.com/ritten-ops-public-logos/rittenBanner"
    backgroundColor: "#FFFFFF"
    altText: "Ritten Logo"
  description: |
    For Ritten Integrating Partners

    ## Authentication

    - Request an access token with your provided integration credentials (`client_id` and `client_secret`) by calling our token endpoint:
    ```bash
    curl https://api.ritten.io/v1/oauth/token \
      -X POST \
      -H 'content-type: application/json' \
      -d '{"client_id":"${client_id}","client_secret":"${client_secret}","audience":"https://external-api.ritten.io","grant_type":"client_credentials"}'
    ```
    - Take the `access_token` from the response and use that as the `Bearer` token in your requests to our API.
    - Tokens are long-lived (24 hours / `expires_in: 86400`). The token endpoint also caches server-side, so rapid repeat calls won't hit Auth0 — but feel free to cache the access_token locally if you prefer.
    - The token endpoint itself does not require a Bearer token; the `client_secret` in the body is the authentication.

    > **Note:** When working in non-production environments, the API endpoints (and `audience` value) will be different.
    > For example, in the `beta` environment, the token endpoint is `https://api.beta.ritten.io/v1/oauth/token`
    > and the audience is `https://external-api.beta.ritten.io`.

    ## Tenant Header

    - Make sure to add the tenant ID to the header of every request. This is the Ritten Clinic instance the request will target. Example:
    ```
    X-Ritten-Tenant: ritclinic
    ```
    
    ## Rate Limiting

    Two layers of rate limiting apply: per-request limits on API calls, and per-app limits on token minting.

    ### API request rate limit

    Applied to authenticated API calls (everything except `/v1/oauth/token`):

    - 50 requests per second sustained rate
    - 100 requests burst allowance

    You can make up to 100 requests in a short burst, but over time your average must stay at or below 50 requests per second. Think of it as a bucket that holds 100 tokens and refills at 50 tokens per second. Each request consumes one token. You'll receive a `429 Too Many Requests` response when this is triggered.

    ### Token mint quota (Auth0)

    A separate per-application limit on how often you can mint new access tokens:

    - 2 mints per hour
    - 3 mints per day

    These limits are applied at the Auth0 layer and count mints across both the legacy direct path and the cached `/v1/oauth/token` endpoint combined. **The cached endpoint is designed so that one mint per day is sufficient for any traffic volume** — the proxy serves all subsequent requests from the cached token. If you migrate to the cached endpoint, you will not notice these limits.

    Token mint quotas currently apply to all newly-provisioned integrator clients. They will be rolled out to existing clients on a separate schedule, and you will be contacted before that change applies to you.
  version: 1.0.0
servers:
  - url: https://api.ritten.io/v1
tags:
  - name: oauth
    description: |
      OAuth 2.0 token endpoint for obtaining access tokens. This is the
      recommended way to authenticate with the Ritten External API.
  - name: patients
  - name: contacts
  - name: users
  - name: calendar
  - name: insurance
  - name: encounters
    description: |
      Endpoints for creating clinical encounters (visits) and discovering the
      encounter types they are created from.
  - name: forms
    description: |
      Endpoints for accessing form definitions and form-related data.
  - name: insights
    description: |
      Ritten provides insights and reporting endpoints for analytics and data export.
      These endpoints return various reports about admissions, discharges, census, billing, and CRM data.

      Most endpoints support CSV export via the `csv=true` query parameter.
  - name: cases
    description: |
      Endpoints for accessing CRM cases (admissions pipeline).
  - name: facilities
    description: |
      Endpoints for accessing clinic facilities (service locations).
  - name: programs
    description: |
      Endpoints for creating, accessing, and managing clinic programs.
  - name: organizations
    description: |
      Endpoints for accessing CRM organizations and organization members. Requires CRM to be available for the target clinic (`X-Ritten-Tenant`). Integrations must be explicitly provisioned by Ritten for organization access.
  - name: tasks
    description: |
      Endpoints for accessing clinic tasks. Tasks linked to a client are only returned when the integration is authorized to read that client.
  - name: webhooks
    description: |
      Ritten provides webhooks for various events that occur in the system.
      Integrating partners can subscribe to these events to receive real-time updates.

      Webhooks sent from Ritten are POST requests with a JSON body containing the event `type` and associated `data`.
      The schema for the `data` object will vary depending on the event type.
      ```
      {
        "type": "patient.admit",
        "data": {
          "patientId": "182c2e54-3494-4b85-aba5-038cf539d5bf",
          "programId": "9a5e64b0-0a73-4cb5-ab32-44fea16da4e1"
        }
      }
      ```

paths:
  /oauth/token:
    post:
      tags:
        - oauth
      summary: Obtain an access token (OAuth 2.0 client_credentials)
      description: |
        Exchanges integrator credentials for a 24-hour access token to use as a `Bearer`
        token on subsequent API calls. This endpoint is **unauthenticated** at the gateway
        layer — your `client_secret` in the request body is the authentication. Ritten
        forwards the credentials to Auth0, validates the response, and caches the resulting
        token server-side so repeated calls do not consume your Auth0 mint quota.

        The response shape mirrors the OAuth 2.0 / Auth0 `/oauth/token` response so existing
        OAuth2 client libraries work without modification.

        **Mint quota interaction:** the per-app token mint quota (2/hour, 3/day) counts
        mints actually performed against Auth0. Because this endpoint caches server-side,
        repeated calls within a 24-hour window typically result in zero additional Auth0
        mints — so calling here is far cheaper against your quota than calling Auth0
        directly. See the Authentication and Rate Limiting sections above.
      operationId: postOAuthToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OAuthTokenRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/OAuthTokenRequest"
      responses:
        200:
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
        400:
          description: |
            Malformed request. The `error` field will be one of `invalid_request`,
            `unsupported_grant_type`, or `invalid_audience`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
        401:
          description: |
            Auth0 rejected the supplied credentials (`error: invalid_client` or similar).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
        429:
          description: |
            Rate limit exceeded. Either the per-IP request rate limit on this endpoint,
            or the per-app Auth0 mint quota (2/hour, 3/day) has been reached. Retry
            after a short delay. If 429s persist, inspect whether you are hitting
            per-IP request limits vs. triggering fresh Auth0 mints, then reach out
            to Ritten for support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
        502:
          description: |
            Auth0 was unreachable or returned a 5xx error. Retry — Ritten does not
            cache failed responses.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
  /patients:
    get:
      tags:
        - patients
      summary: List patients in a clinic
      description: Lists patients in a clinic
      operationId: listPatients
      parameters:
        - name: programStatus
          in: query
          description: Patient Program status filter
          required: true
          schema:
            type: string
            enum:
              - prospective
              - active
              - former
        - name: limit
          in: query
          description: How many patients to return at one time (max 20).
          schema:
            maximum: 20
            type: integer
            format: int64
        - name: offset
          in: query
          description:
            How many patients to skip before returning the limit number of
            patients. Use this to page.
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPatients"
    post:
      tags:
        - patients
      summary: Create a new patient
      description: Creates a new patient record (this will generate an MRN and put the patient in 'prospective' status)
      operationId: createPatient
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  $ref: "#/components/schemas/PatientName"
                dob:
                  type: string
                  description: Date of birth (YYYY-MM-DD)
                  example: "1990-02-23"
                externalId:
                  type: string
                  description: An external identifier for the patient (e.g. an ID from a third-party system)
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDSchema"
  /patients/{id}:
    get:
      tags:
        - patients
      summary: Retrieve a patient by ID
      description: Returns a single patient
      operationId: getPatientById
      parameters:
        - name: id
          in: path
          description: ID of patient to return
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientDetail"
        400:
          description: Invalid ID supplied
        404:
          description: Patient not found
    patch:
      tags:
        - patients
      summary: Update a patient by ID
      description: |
        Update a single patient. Returns the updated patient.
        Omitting a top-level field in the request body will leave it unchanged.
      operationId: patchPatient
      parameters:
        - name: id
          in: path
          description: ID of patient to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  allOf:
                    - $ref: "#/components/schemas/PatientName"
                  description: The patient's name. Omitted nested fields are left unchanged.
                dob:
                  type: string
                  description: Date of birth (YYYY-MM-DD)
                  example: "1990-02-23"
                ssn:
                  type: string
                  writeOnly: true
                  description: Full Social Security number. Accepted with or without dashes and never returned in patient responses.
                  examples:
                    - "123-45-6789"
                    - "123456789"
                demographics:
                  $ref: "#/components/schemas/PatientDemographics"
                emails:
                  type: array
                  items:
                    type: string
                    example: "john@example.com"
                phones:
                  type: array
                  items:
                    type: string
                    example: "+15555555555"
                addresses:
                  type: array
                  items:
                    $ref: "#/components/schemas/Address"
                  description: The patient's addresses. To update an existing address, include the address ID.
                referrals:
                  type: array
                  items:
                    $ref: "#/components/schemas/Referral"
                  description: The patient's referrals. To update an existing referral, include the referral ID.
                insurance:
                  type: array
                  items:
                    $ref: "#/components/schemas/Insurance"
                  description: The patient's insurance information. To update an existing insurance record, include the insurance ID.
                externalId:
                  type: string
                  description: An external identifier for the patient (e.g. an ID from a third-party system)
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientDetail"
        400:
          description: Invalid ID or payload supplied
        404:
          description: Patient not found
  /patients/{id}/vitals:
    post:
      tags:
        - patients
      summary: Record patient vitals
      description: |
        Records a single vital observation for the patient. Units are fixed by observation and measurement type;
        do not include units in the request body.
      operationId: postPatientVitals
      parameters:
        - name: id
          in: path
          description: ID of patient to record vitals for
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPatientVital"
            examples:
              temperature:
                summary: Temperature in Fahrenheit
                value:
                  type: temperature
                  measurements:
                    - value: 98.6
                  timestamp: "2026-05-27T15:30:00Z"
              heart_rate:
                summary: Heart rate in beats per minute
                value:
                  type: heart_rate
                  measurements:
                    - value: 72
                  timestamp: "2026-05-27T15:30:00Z"
              respiration_rate:
                summary: Respiration rate in breaths per minute
                value:
                  type: respiration_rate
                  measurements:
                    - value: 16
                  timestamp: "2026-05-27T15:30:00Z"
              oxygen_saturation:
                summary: Oxygen saturation percentage
                value:
                  type: oxygen_saturation
                  measurements:
                    - value: 98
                  timestamp: "2026-05-27T15:30:00Z"
              blood_pressure:
                summary: Blood pressure in mmHg
                value:
                  type: blood_pressure
                  measurements:
                    - type: systolic
                      value: 120
                    - type: diastolic
                      value: 80
                  timestamp: "2026-05-27T15:30:00Z"
              glucose:
                summary: Glucose in mg/dL
                value:
                  type: glucose
                  measurements:
                    - value: 110
                  timestamp: "2026-05-27T15:30:00Z"
              blood_alcohol_concentration:
                summary: Blood alcohol concentration percentage
                value:
                  type: blood_alcohol_concentration
                  measurements:
                    - value: 0.02
                  timestamp: "2026-05-27T15:30:00Z"
              height_weight_height_only:
                summary: Height in total inches
                value:
                  type: height_weight
                  measurements:
                    - type: height
                      value: 70
                  timestamp: "2026-05-27T15:30:00Z"
              height_weight_weight_only:
                summary: Weight in pounds
                value:
                  type: height_weight
                  measurements:
                    - type: weight
                      value: 180
                  timestamp: "2026-05-27T15:30:00Z"
              height_weight_both:
                summary: Height in total inches and weight in pounds
                value:
                  type: height_weight
                  measurements:
                    - type: height
                      value: 70
                    - type: weight
                      value: 180
                  timestamp: "2026-05-27T15:30:00Z"
      responses:
        204:
          description: Vital recorded successfully
        400:
          description: Invalid ID or payload supplied
        404:
          description: Patient not found
  /patients/{id}/forms:
    post:
      tags:
        - forms
      summary: Create a form on a patient chart and submit field values
      description: |
        Creates a form instance from a pre-configured form definition (resolved by its label) on the
        patient's chart and writes all provided field values in a single atomic call — on any error,
        nothing is written. Use `GET /forms/definitions` to discover form, section, and field labels.

        Every ingested form attaches to an existing encounter (visit) on the patient's chart: create
        the encounter first, then submit form data with its `encounterId`. The encounter must belong
        to the patient.

        Values are keyed by field definition label and must match the field's type: strings for
        `text` and `text_paragraph`, `YYYY-MM-DD` or RFC 3339 strings for `date`, numbers for
        `number_float`, a configured choice string for single-choice fields (scale answers are string
        integers, e.g. `"2"`), and arrays of choice strings for multi-choice fields. Grid-matrix
        values are row-keyed objects whose per-row shape depends on the sub-type: `grid_matrix_text`
        and `grid_matrix_number` map each row index to a column-keyed object of cells
        (`{"0": {"1": "cell"}}`), `grid_matrix_choice` maps each row index to a single integer column
        index (`{"0": 1}`), and `grid_matrix_multi_choice` maps each row index to an array of integer
        column indices (`{"0": [0, 1]}`). A JSON `null` clears a field (including any default).
        Display-only, calculated, and chart-backed (`roobi_custom_field`) fields cannot be written.
        Omit `values` to create an empty form.

        Submitted field labels must be unambiguous within the form definition: if a label matches more
        than one field on the created form, the request fails with a 400.

        The created form behaves exactly like one created on the encounter in-app: it arrives
        unsigned with the definition's signature requirements and signature actions, signers are
        notified, due-forms scheduling applies, and the encounter's documentation status is
        recalculated. Requests are not idempotent: retrying a successful call creates a second form
        instance.
      operationId: postPatientForm
      parameters:
        - name: id
          in: path
          description: ID of the patient to create the form for
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPatientForm"
            examples:
              phq9:
                summary: Submit a PHQ-9 assessment
                value:
                  formDefinitionLabel: phq9_intake_form
                  encounterId: "6a6f8ab1-38b0-4c96-9f39-2a37e2f4a111"
                  values:
                    roobi_depression_phq9_q1: "2"
                    roobi_depression_phq9_q2: "3"
                    reason_for_visit: referral
              empty_form:
                summary: Create an empty form (no values)
                value:
                  formDefinitionLabel: weekly_progress_note
                  encounterId: "6a6f8ab1-38b0-4c96-9f39-2a37e2f4a111"
      responses:
        200:
          description: Form created and all values written
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientForm"
        400:
          description: Invalid payload — unknown or ambiguous field label, value invalid for the field's type, or unsupported form definition
        404:
          description: Patient, form definition label, or encounter not found
  /patients/{id}/relationships:
    get:
      tags:
        - patients
      summary: List a patient's relationships
      description: Returns a list of relationships for a patient
      operationId: listPatientRelationships
      parameters:
        - name: id
          in: path
          description: ID of patient to return relationships for
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PatientRelationship"
        400:
          description: Invalid ID supplied
        404:
          description: Patient not found
    post:
      tags:
        - patients
      summary: Create a new patient relationship
      description: Creates a new relationship between two patients
      operationId: createPatientRelationship
      parameters:
        - name: id
          in: path
          description: ID of patient to create a relationship for
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - personId
                - type
              properties:
                personId:
                  type: string
                  description: ID of the person to create a relationship with (patient or contact)
                type:
                  type: string
                  description: The type of relationship
                isEmergencyContact:
                  type: boolean
                isGuarantor:
                  type: boolean
                isGuardian:
                  type: boolean
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientRelationship"
        400:
          description: Invalid payload supplied
  /patients/{id}/relationships/{relationshipId}:
    patch:
      tags:
        - patients
      summary: Update a patient relationship
      description: |
        Update a single patient relationship. Returns the updated relationship.
        Omitting a top-level field in the request body will leave it unchanged.
      operationId: patchPatientRelationship
      parameters:
        - name: id
          in: path
          description: ID of patient to update a relationship for
          required: true
          schema:
            type: string
        - name: relationshipId
          in: path
          description: ID of relationship to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The type of relationship
                isEmergencyContact:
                  type: boolean
                isGuarantor:
                  type: boolean
                isGuardian:
                  type: boolean
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientRelationship"
        400:
          description: Invalid ID or payload supplied
        404:
          description: Relationship not found
    delete:
      tags:
        - patients
      summary: Delete a patient relationship
      description: Deletes a patient relationship by ID
      operationId: deletePatientRelationship
      parameters:
        - name: id
          in: path
          description: ID of patient to delete a relationship for
          required: true
          schema:
            type: string
        - name: relationshipId
          in: path
          description: ID of relationship to delete
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
  /patients/{id}/attachments:
    post:
      tags:
        - patients
      summary: Attach a document to a patient chart
      description:
        Uploads a file to Ritten and then attaches it as a document on the
        patient chart which lives under the Attachments section in the Platform
      operationId: attachDocument
      parameters:
        - name: id
          in: path
          description: ID of patient
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
                - title
                - type
              properties:
                type:
                  description: The Ritten document type. This can also include any custom types defined by the clinic.
                  $ref: "#/components/schemas/DocumentTypeEnum"
                title:
                  type: string
                  description: The display title of the document
                file:
                  type: string
                  description: The file upload
                  format: binary
        required: true
      responses:
        200:
          description: success
  /patients/{id}/attachments/{attachmentId}:
    patch:
      tags:
        - patients
      summary: Update a document on a patient chart
      description: Update the title and/or type of an existing document on a patient chart. Omitting a field will leave it unchanged.
      operationId: updateDocument
      parameters:
        - name: id
          in: path
          description: ID of patient
          required: true
          schema:
            type: string
        - name: attachmentId
          in: path
          description: ID of attachment to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  description: The Ritten document type. This can also include any custom types defined by the clinic.
                  $ref: "#/components/schemas/DocumentTypeEnum"
                title:
                  type: string
                  description: The display title of the document
      responses:
        200:
          description: success
  /patients/external/{externalId}:
    get:
      tags:
        - patients
      summary: Retrieve a patient by external ID
      description: Returns a single patient with the given external ID
      operationId: getPatientByExternalId
      parameters:
        - name: externalId
          in: path
          description: External ID of patient to return
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatientDetail"
        404:
          description: Patient not found
  /contacts:
    get:
      tags:
        - contacts
      summary: List contacts in a clinic
      description: Lists contacts in a clinic
      operationId: listContacts
      parameters:
        - name: limit
          in: query
          description: How many contacts to return at one time (max 20).
          schema:
            maximum: 20
            type: integer
            format: int64
        - name: offset
          in: query
          description:
            How many contacts to skip before returning the limit number of
            contacts. Use this to page.
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListContacts"
    post:
      tags:
        - contacts
      summary: Create a new contact
      description: Creates a new contact record
      operationId: createContact
      requestBody:
        content:
          application/json:
            schema:
              required:
                - first
                - last
              properties:
                first:
                  type: string
                  description: The contact's first name
                  example: John
                middle:
                  type: string
                  description: The contact's middle name
                last:
                  type: string
                  description: The contact's last name
                  example: Doe
                dob:
                  type: string
                  description: Date of birth (YYYY-MM-DD)
                  example: "1990-02-23"
                address:
                  $ref: "#/components/schemas/Address"
                contactPoints:
                  type: array
                  items:
                    $ref: "#/components/schemas/ContactPoint"
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactDetail"
        400:
          description: Invalid payload supplied
  /contacts/{id}:
    get:
      tags:
        - contacts
      summary: Retrieve a contact by ID
      description: Returns a single contact
      operationId: getContactById
      parameters:
        - name: id
          in: path
          description: ID of contact to return
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactDetail"
        400:
          description: Invalid ID supplied
        404:
          description: Contact not found
    patch:
      tags:
        - contacts
      summary: Update a contact by ID
      description: |
        Update a single contact. Returns the updated contact.
        Omitting a top-level field in the request body will leave it unchanged.
      operationId: patchContact
      parameters:
        - name: id
          in: path
          description: ID of contact to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                first:
                  type: string
                  description: The contact's first name
                  example: John
                middle:
                  type: string
                  description: The contact's middle name
                last:
                  type: string
                  description: The contact's last name
                  example: Doe
                dob:
                  type: string
                  description: Date of birth (YYYY-MM-DD)
                  example: "1990-02-23"
                address:
                  $ref: "#/components/schemas/Address"
                contactPoints:
                  type: array
                  items:
                    $ref: "#/components/schemas/ContactPoint"
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactDetail"
        400:
          description: Invalid ID or payload supplied
        404:
          description: Contact not found
  /contacts/{id}/relationships:
    get:
      tags:
        - contacts
      summary: List a contact's relationships
      description: Returns a list of relationships for a contact
      operationId: listContactRelationships
      parameters:
        - name: id
          in: path
          description: ID of contact to return relationships for
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ContactRelationship"
        400:
          description: Invalid ID supplied
        404:
          description: Contact not found
    post:
      tags:
        - contacts
      summary: Create a new contact relationship
      description: Creates a new relationship between two contacts
      operationId: createContactRelationship
      parameters:
        - name: id
          in: path
          description: ID of contact to create a relationship for
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - personId
                - type
              properties:
                personId:
                  type: string
                  description: ID of the person to create a relationship with (patient or contact)
                type:
                  type: string
                  description: The type of relationship
      responses:
        200:
          description: success
        400:
          description: Invalid payload supplied
  /facilities:
    get:
      tags:
        - facilities
      summary: List active facilities in a clinic
      description: Lists active clinic facilities with pagination and optional filters.
      operationId: listFacilities
      parameters:
        - name: createdAfter
          in: query
          description: Return facilities created after this timestamp (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: search
          in: query
          description: Case-insensitive search on facility name.
          schema:
            type: string
            maxLength: 255
        - name: limit
          in: query
          description: How many facilities to return at one time (max 20).
          schema:
            maximum: 20
            minimum: 1
            type: integer
            format: int64
            default: 20
        - name: offset
          in: query
          description: How many facilities to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
            default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListFacilities"
        400:
          description: Invalid query parameters
    post:
      tags:
        - facilities
      summary: Create a facility in a clinic
      description: Creates a clinic facility. The request must include name, nationalProviderId, phone, and address.
      operationId: postFacility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostFacilityBody"
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Facility"
        400:
          description: Invalid payload supplied
  /facilities/{id}:
    patch:
      tags:
        - facilities
      summary: Update a facility
      description: Updates an active facility.
      operationId: patchFacility
      parameters:
        - name: id
          in: path
          required: true
          description: Facility ID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchFacilityBody"
      responses:
        204:
          description: Facility updated successfully.
        400:
          description: Invalid payload supplied
        404:
          description: Facility not found
  /programs:
    post:
      tags:
        - programs
      summary: Create a clinic program
      description: |
        Creates a clinic program. Requires name, programType, and at least one levelOfCare entry.
        The server assigns the program ID; client-supplied id values and other unknown fields are rejected.
        levelOfCare entries must be exact catalog strings, unique, and compatible with programType.
        facilityId is optional.
      operationId: postProgram
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostProgramBody"
      responses:
        201:
          description: Program created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClinicProgram"
        400:
          description: Invalid payload supplied
    get:
      tags:
        - programs
      summary: List active programs in a clinic
      description: Lists active clinic programs with pagination and optional filters. Archived programs are never returned by the external API.
      operationId: listPrograms
      parameters:
        - name: facilityId
          in: query
          description: Filter programs by active facility ID.
          schema:
            type: string
            format: uuid
        - name: programType
          in: query
          description: Filter programs by type.
          schema:
            $ref: "#/components/schemas/ProgramType"
        - name: search
          in: query
          description: Case-insensitive search on program name.
          schema:
            type: string
            maxLength: 255
        - name: limit
          in: query
          description: How many programs to return at one time (max 200).
          schema:
            maximum: 200
            minimum: 1
            type: integer
            format: int64
            default: 200
        - name: offset
          in: query
          description: How many programs to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
            default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPrograms"
        400:
          description: Invalid query parameters
  /programs/{id}:
    get:
      tags:
        - programs
      summary: Get an active program
      description: Gets an active clinic program by ID. Archived programs are treated as not found.
      operationId: getProgram
      parameters:
        - name: id
          in: path
          required: true
          description: Program ID.
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClinicProgram"
        404:
          description: Program not found
    patch:
      tags:
        - programs
      summary: Update a clinic program
      description: |
        Partially updates an active clinic program's name and/or facility association.
        At least one of name or facilityId must be provided; omitted fields are left unchanged.
        programType and levelOfCare cannot be updated via this endpoint.
        A malformed facilityId UUID returns 400. A missing or archived facilityId returns 404.
      operationId: patchProgram
      parameters:
        - name: id
          in: path
          required: true
          description: Program ID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchProgramBody"
      responses:
        204:
          description: Program updated successfully.
        400:
          description: Invalid payload supplied
        404:
          description: Program not found, or referenced facility not found or archived
  /organizations:
    get:
      tags:
        - organizations
      summary: List active organizations in a clinic
      description: Lists active CRM organizations with pagination and optional filters. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: listOrganizations
      parameters:
        - name: search
          in: query
          description: Case-insensitive search on organization name.
          schema:
            type: string
        - name: organizationTypeIds
          in: query
          description: Filter by one or more organization type IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: assignedUserIds
          in: query
          description: Filter by one or more assigned user IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: tagIds
          in: query
          description: Filter by one or more tag IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: matchAllTags
          in: query
          description: When true, only return records that have ALL selected tags (AND). Default false returns records matching ANY selected tag (OR).
          schema:
            type: boolean
            default: false
        - name: sortBy
          in: query
          description: Sort order for returned organizations.
          schema:
            type: string
            enum:
              - name_asc
              - name_desc
              - createdAt_asc
              - createdAt_desc
        - name: limit
          in: query
          description: How many organizations to return at one time (max 20).
          schema:
            maximum: 20
            minimum: 1
            type: integer
            format: int64
            default: 20
        - name: offset
          in: query
          description: How many organizations to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
            default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListOrganizations"
        400:
          description: Invalid query parameters
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
    post:
      tags:
        - organizations
      summary: Create an organization in a clinic
      description: Creates a CRM organization with optional contact, website, address, assigned user, and primary contact information. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: postOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostOrganizationBody"
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        400:
          description: Invalid payload supplied
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
  /organizations/{id}:
    get:
      tags:
        - organizations
      summary: Get an active organization
      description: Returns a single active CRM organization by ID. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: getOrganization
      parameters:
        - name: id
          in: path
          required: true
          description: Organization ID.
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        400:
          description: Invalid organization ID
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
    patch:
      tags:
        - organizations
      summary: Update an organization
      description: Updates direct flat fields on an active CRM organization. Nested resources such as contact points, tags, addresses, and primary contacts are not supported by this endpoint. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: patchOrganization
      parameters:
        - name: id
          in: path
          required: true
          description: Organization ID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchOrganizationBody"
      responses:
        204:
          description: Organization updated successfully.
        400:
          description: Invalid payload supplied
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
  /organizations/{id}/members:
    get:
      tags:
        - organizations
      summary: List active organization members
      description: Lists member relationships for an active CRM organization. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: listOrganizationMembers
      parameters:
        - name: id
          in: path
          required: true
          description: Organization ID.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: How many members to return at one time (max 20).
          schema:
            maximum: 20
            minimum: 1
            type: integer
            format: int64
            default: 20
        - name: offset
          in: query
          description: How many members to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
            default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListOrganizationMembers"
        400:
          description: Invalid query parameters
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
  /tasks:
    get:
      tags:
        - tasks
      summary: List tasks in a clinic
      description: |
        Lists tasks with pagination and optional filters. Tasks linked to a client are only
        returned when the integration is authorized to read that client; unauthorized tasks
        are excluded from both the results and `meta.totalCount`.

        `title` and `description` are unstructured clinical free text and may contain PHI.
      operationId: listTasks
      parameters:
        - name: assigneeIds
          in: query
          description: Filter by one or more assignee user IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: creatorIds
          in: query
          description: Filter by one or more creator user IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: patientIds
          in: query
          description: Filter by one or more linked client IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: statuses
          in: query
          description: Filter by one or more task statuses.
          schema:
            type: array
            items:
              $ref: "#/components/schemas/TaskStatus"
          style: form
          explode: true
        - name: priorities
          in: query
          description: Filter by one or more task priorities.
          schema:
            type: array
            items:
              $ref: "#/components/schemas/TaskPriority"
          style: form
          explode: true
        - name: dueStartDate
          in: query
          description: Only return tasks due on or after this date. Tasks with no due date are excluded when either due date filter is set.
          schema:
            type: string
            format: date
            example: "2024-01-01"
        - name: dueEndDate
          in: query
          description: Only return tasks due on or before this date.
          schema:
            type: string
            format: date
            example: "2024-01-31"
        - name: createdStartTime
          in: query
          description: Only return tasks created at or after this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: "2024-01-01T00:00:00Z"
        - name: createdEndTime
          in: query
          description: Only return tasks created at or before this ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
            example: "2024-01-31T23:59:59Z"
        - name: sort
          in: query
          description: How to order the results. Defaults to newest created first.
          schema:
            type: string
            enum:
              - activity_newest
              - activity_oldest
              - created_newest
              - created_oldest
              - due_latest
              - due_earliest
              - priority_highest
              - priority_lowest
              - client_az
              - client_za
        - name: limit
          in: query
          description: How many tasks to return at one time (max 20).
          schema:
            maximum: 20
            minimum: 1
            type: integer
            format: int64
            default: 20
        - name: offset
          in: query
          description: How many tasks to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
            default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListTasks"
        400:
          description: Invalid query parameters
    post:
      tags:
        - tasks
      summary: Create a task
      description: |
        Creates a task assigned to a staff member. The server assigns the id, timestamps and
        the creator; `status` defaults to `New` and `priority` to `Medium`.

        The assignee is notified exactly as they would be for a task created in the app.
        Requests are not idempotent: retrying a successful call creates a second task.
      operationId: postTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostTaskBody"
      responses:
        200:
          description: Task created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        400:
          description: Invalid payload supplied
        404:
          description: No staff user found for the supplied assigneeId
  /tasks/{id}:
    patch:
      tags:
        - tasks
      summary: Update a task
      description: |
        Applies a partial update to an existing task. Only the fields you send are changed;
        everything else on the task is left as it is.

        Setting `description` replaces any rich text the task carries, so the text you send
        is what staff see in the app.
      operationId: patchTask
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the task to update.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchTaskBody"
      responses:
        200:
          description: Task updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        400:
          description: Invalid payload supplied, or no fields set
        404:
          description: Task not found, or no staff user found for the supplied assigneeId
  /cases:
    get:
      tags:
        - cases
      summary: List cases in a clinic
      description: Lists CRM cases (admissions pipeline) in a clinic
      operationId: listCases
      parameters:
        - name: limit
          in: query
          description: How many cases to return at one time (max 20, min 0).
          schema:
            maximum: 20
            minimum: 0
            type: integer
            format: int64
        - name: offset
          in: query
          description: How many cases to skip before returning results. Use for pagination.
          schema:
            minimum: 0
            type: integer
            format: int64
        - name: tagIds
          in: query
          description: Filter by one or more tag IDs.
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: true
        - name: matchAllTags
          in: query
          description: When true, only return records that have ALL selected tags (AND). Default false returns records matching ANY selected tag (OR).
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListCases"
        400:
          description: Invalid query parameters
    post:
      tags:
        - cases
      summary: Create a case
      description: Creates a new CRM case (deal). Case status cannot be set during creation; all cases are created with status "new". Tags and caseSource must be provided as plain text names and must match existing values in the system.
      operationId: createCase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCaseBody"
      responses:
        200:
          description: Successfully created case
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Case"
        400:
          description: Bad request (validation error, unknown tag or case source)
        401:
          description: Unauthorized
  /cases/{id}:
    get:
      tags:
        - cases
      summary: Retrieve a case by ID
      description: Returns a single CRM case
      operationId: getCase
      parameters:
        - name: id
          in: path
          description: ID of the case to return
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Case"
        400:
          description: Invalid ID supplied
        404:
          description: Case not found
    patch:
      tags:
        - cases
      summary: Update a case
      description: Updates an existing CRM case (deal). Case status cannot be updated through this endpoint. Tags and caseSource must be provided as plain text names and must match existing values in the system.
      operationId: updateCase
      parameters:
        - name: id
          in: path
          description: The ID of the case to update
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchCaseBody"
      responses:
        200:
          description: Successfully updated case
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Case"
        400:
          description: Bad request (validation error, unknown tag or case source)
        401:
          description: Unauthorized
        404:
          description: Case not found
  /cases/{id}/notes:
    post:
      tags:
        - cases
      summary: Create a case note
      description: Adds a plain-text note to an existing CRM case.
      operationId: createCaseNote
      parameters:
        - name: id
          in: path
          description: The ID of the case to add a note to
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCaseNoteBody"
      responses:
        200:
          description: Successfully created case note
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaseNote"
        400:
          description: Bad request (validation error)
        401:
          description: Unauthorized
        404:
          description: Case not found
  /cases/{id}/action-items:
    post:
      tags:
        - cases
      summary: Create a case action item
      description: |
        Adds an action item to an existing CRM case. Action items are the follow-up
        tasks shown on the case in-app.

        Newly created action items are always incomplete; completing one is not
        supported through this API. Requests are not idempotent: retrying a
        successful call creates a second action item.
      operationId: createCaseActionItem
      parameters:
        - name: id
          in: path
          description: The ID of the case to add an action item to
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCaseActionItemBody"
      responses:
        200:
          description: Successfully created case action item
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaseActionItem"
        400:
          description: Bad request (validation error, or the case is archived)
        401:
          description: Unauthorized
        404:
          description: Case not found
  /encounters:
    post:
      tags:
        - encounters
      summary: Create an encounter
      description: |
        Creates a new, empty encounter (visit) on a patient's chart from an encounter
        type. Use `GET /encounter-types` to discover the available types. The
        encounter starts at server time with no documentation; forms are attached
        separately via `POST /patients/{id}/forms`.

        The new encounter behaves exactly like one created in-app: forms and documents
        configured on the encounter type are seeded onto it, and billing artifacts are
        generated asynchronously for billable types. Requests are not idempotent:
        retrying a successful call creates a second encounter.
      operationId: postEncounter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostEncounterBody"
      responses:
        200:
          description: Encounter created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Encounter"
        400:
          description: Invalid payload supplied
        404:
          description: Patient or encounter type not found (archived encounter types are treated as not found)
  /encounter-types:
    get:
      tags:
        - encounters
      summary: List encounter types
      description: |
        Lists the clinic's active encounter types — the configured visit types that
        encounters are created from. Archived encounter types are never returned by
        the external API.
      operationId: listEncounterTypes
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EncounterType"
  /staff:
    get:
      tags:
        - users
      summary: List all clinic staff users
      description: List all clinic staff users
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users:
    post:
      tags:
        - users
      summary: Create a new user
      description: Creates a new user in the system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: The user's first name
                  example: John
                lastName:
                  type: string
                  description: The user's last name
                  example: Doe
                email:
                  type: string
                  description: The user's email address
                  example: john@example.com
              required:
                - firstName
                - lastName
                - email
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The new user's ID
                  newUserPassword:
                    type: string
                    description: The new user's initial password
  /users/{id}:
    delete:
      tags:
        - users
      summary: Delete a user
      description: Deletes a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: ID of user to delete
      responses:
        200:
          description: User deleted successfully
  /users/{id}/roles:
    post:
      tags:
        - users
      summary: Assign a role to a user
      description: Assigns a role to a user by user ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: ID of user to assign role to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roleId:
                  type: string
                  format: uuid
                  description: ID of role to assign
              required:
                - roleId
      responses:
        200:
          description: Role assigned successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDSchema"
  /users/{id}/roles/{roleID}:
    delete:
      tags:
        - users
      summary: Remove a role from a user
      description: Removes a role from a user by user ID and role ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: ID of user to remove role from
        - name: roleID
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: ID of role to remove
      responses:
        200:
          description: Role removed successfully
  /teams:
    get:
      tags:
        - users
      summary: List all clinic teams
      description: Lists all the clinic teams and their users.
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ClinicTeam"
  /calendar/events/list:
    post:
      tags:
        - calendar
      summary: Query calendar events
      description: Lists all calendar events that match the given query parameters. The POST body is the query object.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - startTime
                - endTime
              properties:
                entityIds:
                  type: array
                  items:
                    type: string
                    example: f87e1b07-1d20-4c36-8c37-08600daf7322
                startTime:
                  type: string
                  description: ISO Format DateTime
                  example: "2024-02-13T13:00:00-05:00"
                endTime:
                  type: string
                  description: ISO Format DateTime
                  example: "2024-02-13T23:59:59-05:00"
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CalendarEvent"
  /calendar/events:
    post:
      tags:
        - calendar
      summary: Create a new calendar event
      description: Create a new calendar event.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/CalendarEventCore"
                - type: object
                  properties:
                    timezone:
                      type: string
                      example: America/New_York
                    encounterTemplateId:
                      type: [string, "null"]
                      example: null
                    reminderInterval:
                      $ref: "#/components/schemas/CalendarEventInterval"
                    notifyGuests:
                      type: boolean
                    guests:
                      type: array
                      items:
                        type: object
                        properties:
                          entityType:
                            type: string
                            enum:
                              - user
                              - patient
                              - clinic team
                              - group
                              - program
                              - care team
                          entityId:
                            type: string
                            example: f87e1b07-1d20-4c36-8c37-08600daf7322
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDSchema"
  /insurance/payers:
    get:
      tags:
        - insurance
      summary: List insurance payers
      description: Lists all insurance payers in the system
      operationId: listInsurancePayers
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Payer"
  /insurance/payers/{id}:
    get:
      tags:
        - insurance
      summary: Retrieve an insurance payer by ID
      description: Returns a single insurance payer
      operationId: getInsurancePayerById
      parameters:
        - name: id
          in: path
          description: ID of insurance payer to return
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payer"
        400:
          description: Invalid ID supplied
        404:
          description: Insurance payer not found

  /forms/definitions:
    get:
      tags:
        - forms
      summary: List form definitions
      description: Returns all form definitions configured for the clinic, including section definitions and signature requirements
      operationId: listFormDefinitions
      parameters:
        - name: showArchived
          in: query
          schema:
            type: boolean
            default: false
          description: Include archived form definitions
        - name: isTxPlan
          in: query
          schema:
            type: boolean
            default: false
          description: Filter to only treatment plan forms
        - name: fieldDefinitionIds[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by specific field definition IDs
          style: form
          explode: true
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FormDefinition"
        401:
          description: Unauthorized

  /insights/admissions:
    get:
      tags:
        - insights
      summary: Get admissions report
      description: Returns admissions report for patients admitted within the specified date range
      operationId: getAdmissionsReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range (ISO 8601)
          example: "2024-01-01T00:00:00Z"
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range (ISO 8601)
          example: "2024-01-31T23:59:59Z"
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results to return
        - name: offset
          in: query
          schema:
            type: integer
          description: Number of results to skip for pagination
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return results as CSV file
        - name: clinical
          in: query
          schema:
            type: boolean
            default: false
          description: Filter for clinical programs only
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdmissionsReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid query parameters
        401:
          description: Unauthorized
  /insights/discharges:
    get:
      tags:
        - insights
      summary: Get discharges report
      description: Returns discharge report for patients discharged within the specified date range
      operationId: getDischargesReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: combineTransfers
          in: query
          schema:
            type: boolean
            default: false
          description: Combine transferred programs into episodes of care
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
        - name: clinical
          in: query
          schema:
            type: boolean
            default: false
          description: Filter for clinical programs only
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DischargesReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/alos:
    get:
      tags:
        - insights
      summary: Get average length of stay report
      description: Returns Average Length of Stay (ALOS) report for patients in the specified date range
      operationId: getAlosReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlosReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/program-census:
    get:
      tags:
        - insights
      summary: Get program census report
      description: Returns census statistics by program for the specified date range
      operationId: getProgramCensusReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgramCensusReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/census-report:
    get:
      tags:
        - insights
      summary: Get census report
      description: Returns detailed census report of all active patients in the date range
      operationId: getCensusReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: isBrief
          in: query
          schema:
            type: boolean
            default: false
          description: Return brief version with fewer fields
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CensusReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/dbs:
    get:
      tags:
        - insights
      summary: Get daily billable services report
      description: Returns Daily Billable Services (DBS) report for the specified date range
      operationId: getDbsReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date in format YYYY-MM-DD
          example: "2024-01-01"
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date in format YYYY-MM-DD
          example: "2024-01-31"
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DbsReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/event-audit:
    get:
      tags:
        - insights
      summary: Get event audit report
      description: Returns audit report for calendar events in the specified date range
      operationId: getEventAuditReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: userIds[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by user IDs
          style: form
          explode: true
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventAuditReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unauthorized
  /insights/facility-census:
    get:
      tags:
        - insights
      summary: Get facility census report
      description: Returns facility census report (always returns CSV format)
      operationId: getFacilityCensusReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date in format YYYY-MM-DD
          example: "2024-01-01"
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date in format YYYY-MM-DD
          example: "2024-01-31"
      responses:
        200:
          description: success (CSV only)
          content:
            text/csv:
              schema:
                type: string
        400:
          description: Invalid date format
        401:
          description: Unauthorized
  /insights/clinic-organizations:
    get:
      tags:
        - insights
      summary: Get clinic organizations
      description: Returns list of all clinic organizations from CRM
      operationId: getClinicOrganizations
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationsReport"
            text/csv:
              schema:
                type: string
        401:
          description: Unauthorized
        403:
          description: CRM feature flag not enabled
  /insights/organization-notes:
    get:
      tags:
        - insights
      summary: Get organization notes
      description: Returns notes associated with organizations in the specified date range
      operationId: getOrganizationNotes
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationNotesReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid date range
        401:
          description: Unauthorized
        403:
          description: CRM feature flag not enabled
  /insights/created-cases:
    get:
      tags:
        - insights
      summary: Get created cases report
      description: Returns CRM cases (deals) created within the specified date range
      operationId: getCreatedCases
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedCasesReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid date range
        401:
          description: Unauthorized
        403:
          description: CRM feature flag not enabled
  /insights/disqualified-cases:
    get:
      tags:
        - insights
      summary: Get disqualified cases report
      description: Returns CRM cases (deals) that were disqualified within the specified date range
      operationId: getDisqualifiedCases
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisqualifiedCasesReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid date range
        401:
          description: Unauthorized
        403:
          description: CRM feature flag not enabled

  /insights/care-teams:
    get:
      tags:
        - insights
      summary: Get care teams report
      description: Returns care team assignments for all currently active patients, including primary clinician and up to 10 additional team members with their roles
      operationId: getCareTeamsReport
      parameters:
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CareTeamsReport"
            text/csv:
              schema:
                type: string
        401:
          description: Unauthorized

  /insights/encounter-history:
    get:
      tags:
        - insights
      summary: Get encounter history report
      description: Returns encounter history for patients within the specified date range, including encounter details, attendance, billing information, and associated forms
      operationId: getEncounterHistoryReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range (ISO 8601)
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range (ISO 8601)
        - name: patientIds[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by specific patient IDs
          style: form
          explode: true
        - name: creatorUserId
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by encounter creator user ID
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EncounterHistoryReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters (missing required dates or invalid date format)
        401:
          description: Unauthorized

  /insights/client-event-history:
    get:
      tags:
        - insights
      summary: Get client event history report
      description: Returns a detailed event-level history for patients within the specified date range, including scheduled, occurred, and cancelled events with attendance status and billing information
      operationId: getClientEventHistoryReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range (ISO 8601)
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range (ISO 8601)
        - name: patientIds[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by specific patient IDs
          style: form
          explode: true
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientEventHistoryReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters (missing required dates or invalid date format)
        401:
          description: Unauthorized

  /insights/client-attendance-by-status:
    get:
      tags:
        - insights
      summary: Get client attendance by status report
      description: Returns a summary of event counts per attendance status for each client, grouped by program, level of care, and encounter type
      operationId: getClientAttendanceByStatusReport
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range (ISO 8601)
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range (ISO 8601)
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientAttendanceByStatusReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters (missing required dates or invalid date format)
        401:
          description: Unauthorized

  /insights/form-outcomes:
    get:
      tags:
        - insights
      summary: Get form outcomes report
      description: Returns outcomes data for a specific form definition within the specified date range, including patient information, encounter details, and form field values
      operationId: getFormOutcomesReport
      parameters:
        - name: formDefinitionId
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: The form definition ID to get outcomes for
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date of report range (ISO 8601)
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End date of report range (ISO 8601)
        - name: patientIds[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Filter by specific patient IDs
          style: form
          explode: true
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results to return
        - name: offset
          in: query
          schema:
            type: integer
          description: Number of results to skip for pagination
        - name: csv
          in: query
          schema:
            type: boolean
            default: false
          description: Return as CSV file
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FormOutcomesReport"
            text/csv:
              schema:
                type: string
        400:
          description: Invalid parameters (missing required fields or invalid format)
        401:
          description: Unauthorized

webhooks:
  patient.admit:
    post:
      tags:
        - webhooks
      description: A patient has been admitted to a clinic program
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: patient.admit
                data:
                  type: object
                  properties:
                    patientId:
                      type: string
                      description: The ID of the patient
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    programId:
                      type: string
                      description: The ID of the program the patient was admitted to
                      example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
      responses:
        200:
          description: 200 status indicates that the data was received successfully
  patient.transfer:
    post:
      tags:
        - webhooks
      description: A patient has been transferred from one program to another
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: patient.transfer
                data:
                  type: object
                  properties:
                    patientId:
                      type: string
                      description: The ID of the patient
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    fromProgramId:
                      type: string
                      description: The ID of the program the patient was transferred from
                      example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
                    toProgramId:
                      type: string
                      description: The ID of the program the patient was transferred to
                      example: 1eddacc4-26b1-4e65-bf34-897e3be577c1
      responses:
        200:
          description: 200 status indicates that the data was received successfully
  patient.discharge:
    post:
      tags:
        - webhooks
      description: A patient has been discharged from a clinic program
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: patient.discharge
                data:
                  type: object
                  properties:
                    patientId:
                      type: string
                      description: The ID of the patient
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    programId:
                      type: string
                      description: The ID of the program the patient was discharged from
                      example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
      responses:
        200:
          description: 200 status indicates that the data was received successfully
  case.status.update:
    post:
      tags:
        - webhooks
      description: The status of a case has been updated
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: case.status.update
                data:
                  type: object
                  properties:
                    caseId:
                      type: string
                      description: The ID of the case
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    personSeekingTreatmentId:
                      type: string
                      description: The ID of the person seeking treatment. Can be empty if there is no person seeking treatment associated with the case.
                      example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
                    fromStatus:
                      type: string
                      description: The previous status of the case
                      example: New
                    toStatus:
                      type: string
                      description: The new status of the case
                      example: Qualified
      responses:
        200:
          description: 200 status indicates that the data was received successfully
  case.created:
    post:
      tags:
        - webhooks
      description: A new case has been created
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: case.created
                data:
                  type: object
                  properties:
                    caseId:
                      type: string
                      description: The ID of the case
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    personSeekingTreatmentId:
                      type: string
                      description: The ID of the person seeking treatment. Can be empty if there is no person seeking treatment associated with the case.
                      example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
                    status:
                      type: string
                      description: The status of the case
                      example: New
      responses:
        200:
          description: 200 status indicates that the data was received successfully
  patient.created:
    post:
      tags:
        - webhooks
      description: A new patient has been created (MRN generated)
      requestBody:
        content:
          application/json:
            schema:
              properties:
                type:
                  type: string
                  description: The event type
                  example: patient.created
                data:
                  type: object
                  properties:
                    patientId:
                      type: string
                      description: The ID of the patient
                      example: 182c2e54-3494-4b85-aba5-038cf539d5bf
                    mrn:
                      type: string
                      description: The medical record number assigned to the patient
                      example: D31EBE
      responses:
        200:
          description: 200 status indicates that the data was received successfully

components:
  schemas:
    OAuthTokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
        - audience
      properties:
        grant_type:
          type: string
          enum:
            - client_credentials
          description: OAuth 2.0 grant type. Must be `client_credentials`.
          example: client_credentials
        client_id:
          type: string
          description: Your Auth0 M2M client ID.
        client_secret:
          type: string
          format: password
          writeOnly: true
          description: Your Auth0 M2M client secret.
        audience:
          type: string
          description: |
            The audience for the requested token. Must equal the env-specific
            external-api audience (e.g. `https://external-api.ritten.io` in
            production, `https://external-api.beta.ritten.io` in beta).
          example: https://external-api.ritten.io
    OAuthTokenResponse:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
          description: The access token to use as a `Bearer` token on subsequent API calls.
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          format: int64
          description: Token lifetime in seconds (currently 86400 / 24h).
          example: 86400
        scope:
          type: string
          description: Space-separated list of granted scopes (may be empty).
    OAuthErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: |
            OAuth 2.0 error code. Common values: `invalid_request`,
            `unsupported_grant_type`, `invalid_audience`, `invalid_client`,
            `bad_gateway`, `rate_limit_exceeded`.
        error_description:
          type: string
          description: Human-readable explanation of the error.
    PostPatientVital:
      type: object
      additionalProperties: false
      required:
        - type
        - measurements
        - timestamp
      properties:
        type:
          type: string
          description: |
            Vital observation type. `height_weight` accepts either a height measurement, a weight measurement,
            or both in one observation for compatibility with Ritten's internal biometrics model.
          enum:
            - temperature
            - heart_rate
            - respiration_rate
            - oxygen_saturation
            - blood_pressure
            - glucose
            - blood_alcohol_concentration
            - height_weight
          example: heart_rate
        measurements:
          type: array
          minItems: 1
          maxItems: 2
          description: |
            Measurements for the observation. Omit `type` only when the observation has a single standard
            measurement. `blood_pressure` requires one `systolic` and one `diastolic` measurement.
            `height_weight` supports `height`, `weight`, or both. The maximum of 2 measurements covers
            composite observations such as blood pressure and height/weight.
          items:
            $ref: "#/components/schemas/PostPatientVitalMeasurement"
        timestamp:
          type: string
          format: date-time
          description: Time the vital was recorded.
          example: "2026-05-27T15:30:00Z"
    PostPatientVitalMeasurement:
      type: object
      additionalProperties: false
      required:
        - value
      properties:
        type:
          type: string
          description: |
            Measurement type. Optional for single-measurement vitals, where omitted values default to
            `standard`. Required for composite measurements: `blood_pressure` must include `systolic`
            and `diastolic`, and `height_weight` must use `height` or `weight`. Structural validation is
            enforced server-side.
            Expected units: `standard` temperature = °F, heart_rate and respiration_rate = bpm,
            oxygen_saturation and blood_alcohol_concentration = %, glucose = mg/dL,
            systolic/diastolic = mmHg, height = in, weight = lbs.
          enum:
            - standard
            - systolic
            - diastolic
            - height
            - weight
          example: standard
        value:
          type: number
          format: double
          description: Numeric measurement value in the documented unit for this observation and measurement type.
          example: 72
    AttendanceType:
      type: string
      description: Attendance status of an encounter. Defaults to Attended when omitted at creation.
      enum:
        - Attended
        - AttendedNotBillable
        - AbsentExcused
        - AbsentNotExcused
        - AbsentUnknown
        - AbsentBillable
    PostTaskBody:
      type: object
      additionalProperties: false
      description: |
        External create contract for tasks. The server assigns the id, timestamps and creator.
      required:
        - title
        - assigneeId
      example:
        title: "Call the pharmacy"
        assigneeId: "9a5e64b0-0a73-4cb5-ab32-44fea16da4e1"
        priority: "High"
        dueDate: "2024-01-31"
      properties:
        title:
          type: string
          description: Short summary of the task. Unstructured clinical free text; may contain PHI.
        description:
          type: string
          description: Optional detail. Unstructured clinical free text; may contain PHI. Markdown is rendered.
        assigneeId:
          type: string
          format: uuid
          description: The staff user to assign the task to. Must be an active staff user.
        priority:
          $ref: "#/components/schemas/TaskPriority"
        status:
          $ref: "#/components/schemas/TaskStatus"
        dueDate:
          type: string
          format: date
          description: Date the task is due.
          example: "2024-01-31"
    PatchTaskBody:
      type: object
      additionalProperties: false
      minProperties: 1
      description: |
        External partial update contract for tasks. Only the fields present in the request are
        changed; omitted fields keep their stored value. At least one field must be set.
      example:
        status: "Complete"
      properties:
        title:
          type: string
          description: Short summary of the task. Unstructured clinical free text; may contain PHI.
        description:
          type: string
          description: Unstructured clinical free text; may contain PHI. Replaces any rich text the task carries.
        assigneeId:
          type: string
          format: uuid
          description: The staff user to assign the task to. Must be an active staff user.
        priority:
          $ref: "#/components/schemas/TaskPriority"
        status:
          $ref: "#/components/schemas/TaskStatus"
        dueDate:
          type: string
          format: date
          description: Date the task is due. Send an empty string to clear an existing due date.
          example: "2024-01-31"
    PostEncounterBody:
      type: object
      additionalProperties: false
      description: |
        External create contract for encounters. The server assigns the encounter ID and start time on create.
      required:
        - patientId
        - encounterTypeId
      example:
        patientId: "d3f2c9a1-8b47-4e0f-a2c9-53f7f0c1b2aa"
        encounterTypeId: "0b6a1f6e-2f9a-4c56-9d1c-6a3f6f9d2e11"
        attendanceType: "Attended"
      properties:
        patientId:
          type: string
          format: uuid
          description: ID of the patient to create the encounter for.
        encounterTypeId:
          type: string
          format: uuid
          description: ID of the encounter type to create the encounter from. Use `GET /encounter-types` to discover types.
        attendanceType:
          $ref: "#/components/schemas/AttendanceType"
    Encounter:
      type: object
      properties:
        id:
          type: string
          format: uuid
        patientId:
          type: string
          format: uuid
        encounterTypeId:
          type: string
          format: uuid
          description: ID of the encounter type the encounter was created from.
        name:
          type: string
          description: Display name of the encounter type.
          example: Individual Therapy
        status:
          type: string
          description: Documentation status of the encounter. New encounters always start Empty.
          enum:
            - Empty
            - Incomplete
            - Complete
        startTime:
          type: string
          format: date-time
          description: Start time of the encounter (server time at creation).
          example: "2024-01-01T00:00:00Z"
        attendanceType:
          $ref: "#/components/schemas/AttendanceType"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    EncounterType:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Display name of the encounter type.
          example: Individual Therapy
        description:
          type: string
        isBillable:
          type: boolean
          description: Whether encounters of this type generate billing artifacts.
        isGroup:
          type: boolean
          description: Whether this type is used for group encounters.
        durationMinutes:
          anyOf:
            - type: integer
              format: int64
            - type: "null"
          description: Default duration in minutes, when configured.
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    PostPatientForm:
      type: object
      additionalProperties: false
      required:
        - formDefinitionLabel
        - encounterId
      properties:
        formDefinitionLabel:
          type: string
          description: Label of the form definition to instantiate. Discover labels via `GET /forms/definitions`.
          example: phq9_intake_form
        encounterId:
          type: string
          format: uuid
          description: |
            Encounter (visit) to attach the form to. The encounter must already exist and belong to
            the patient — create the encounter before submitting form data.
        values:
          type: object
          additionalProperties: true
          description: |
            Flat map of field definition label to value. Value shapes are field-type specific (see the
            endpoint description). A JSON null clears the field. Omit to create an empty form.
          example:
            roobi_depression_phq9_q1: "2"
            reason_for_visit: referral
    PatientForm:
      type: object
      properties:
        formInstanceId:
          type: string
          format: uuid
        formDefinitionLabel:
          type: string
          example: phq9_intake_form
        patientId:
          type: string
          format: uuid
        encounterId:
          type: string
          format: uuid
          description: Encounter the form is attached to.
        createdAt:
          type: string
          format: date-time
        sections:
          type: array
          items:
            $ref: "#/components/schemas/PatientFormSection"
    PatientFormSection:
      type: object
      properties:
        sectionLabel:
          type: string
          example: roobi_depression_phq9
        title:
          type: string
          example: PHQ-9
        fields:
          type: array
          items:
            $ref: "#/components/schemas/PatientFormField"
    PatientFormField:
      type: object
      properties:
        fieldLabel:
          type: string
          example: roobi_depression_phq9_q1
        title:
          type: string
          description: The field's prompt text.
        type:
          type: string
          description: The field's type (e.g. text, date, single_choice_scale, grid_matrix_text).
          example: single_choice_scale
        value:
          description: The field's stored value; null when unset.
    ListCases:
      type: array
      items:
        $ref: "#/components/schemas/Case"
    ListTasks:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/Task"
    TaskStatus:
      type: string
      enum:
        - New
        - Working
        - Complete
        - Won't Do
    TaskPriority:
      type: string
      enum:
        - Low
        - Medium
        - High
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "182c2e54-3494-4b85-aba5-038cf539d5bf"
        title:
          type: string
          example: "Call the pharmacy"
        description:
          type: string
          example: "Confirm the refill went through."
        status:
          $ref: "#/components/schemas/TaskStatus"
        priority:
          $ref: "#/components/schemas/TaskPriority"
        assigneeId:
          description: The user the task is assigned to, or null if unassigned.
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          example: "9a5e64b0-0a73-4cb5-ab32-44fea16da4e1"
        createdById:
          description: The user who created the task, or null if it was created by an automation.
          anyOf:
            - type: string
              format: uuid
            - type: "null"
        patientId:
          description: The client the task is linked to, or null if it is not client-linked.
          anyOf:
            - type: string
              format: uuid
            - type: "null"
        dueDate:
          description: The date the task is due, or null if it has no due date.
          anyOf:
            - type: string
              format: date
            - type: "null"
          example: "2024-01-31"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        updatedAt:
          description: When the task was last updated, or null if it has never been updated.
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          example: "2024-01-02T00:00:00Z"
        statusUpdatedAt:
          description: When the task's status last changed, or null if it has never changed.
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          example: "2024-01-02T00:00:00Z"
    ListFacilities:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        facilities:
          type: array
          items:
            $ref: "#/components/schemas/Facility"
    Facility:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        address:
          $ref: "#/components/schemas/Address"
        nationalProviderId:
          type: string
          description: National Provider Identifier (NPI)
        phone:
          type: string
          description: Primary facility phone number
          example: "+15555555555"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    ListPrograms:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        programs:
          type: array
          items:
            $ref: "#/components/schemas/ClinicProgram"
    ClinicProgram:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        name:
          type: string
          example: Residential
        facility:
          anyOf:
            - $ref: "#/components/schemas/ProgramFacility"
            - type: "null"
        programType:
          $ref: "#/components/schemas/ProgramType"
        levelOfCare:
          type: array
          items:
            $ref: "#/components/schemas/LevelOfCare"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    ProgramFacility:
      type: object
      properties:
        id:
          type: string
          format: uuid
    ProgramType:
      type: string
      enum:
        - Clinical
        - Additional Service
    LevelOfCare:
      type: string
      enum:
        - Early Intervention (0.5)
        - Outpatient Services (1.0)
        - Long-Term Remission Monitoring (1.0)
        - Outpatient Therapy (1.5)
        - Medically Managed Outpatient (1.7)
        - IOP/PHP - General (2)
        - IOP (2.1)
        - HIOP (High-Intensity Outpatient) (2.5)
        - PHP (2.5)
        - Medically Managed Intensive Outpatient (2.7)
        - Residential - General (3)
        - Clinically Managed Low-Intensity Residential Services (3.1)
        - Clinically Managed Population-Specific High-Intensity Services (3.2)
        - Clinically Managed High-Intensity Residential Services (3.5)
        - Medically Monitored Intensive Inpatient Services (3.7)
        - Medically Managed Residential (3.7)
        - Medically Managed Intensive Inpatient Services (4)
        - Ambulatory Detox Without Extended Onsite Monitoring (I-D)
        - Ambulatory Detox With Extended Onsite Monitoring (II-D)
        - Clinically Managed Residential Detoxification (III.2-D)
        - Medically Monitored Inpatient Detoxification (III.7-D)
        - Medically Managed Intensive Inpatient Detoxification (IV-D)
        - Sober Living
        - Recovery Residence
        - Case Management
        - Monitoring / Drug Testing
        - Peer Support
        - Advisory Services
        - Medication Management
        - Other
        - Other - Clinical
        - Level 3 (3)
        - Significant Treatment (3)
        - Level 4 (4)
        - Level 5 (5)
    ListOrganizations:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        organizations:
          type: array
          items:
            $ref: "#/components/schemas/Organization"
    ListOrganizationMembers:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        members:
          type: array
          items:
            $ref: "#/components/schemas/OrganizationMember"
    Organization:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization, if any.
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: "https://example.com"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    OrganizationMember:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Organization-person relationship ID.
        personId:
          type: string
          format: uuid
        first:
          type: string
          example: Jane
        last:
          type: string
          example: Doe
    PostOrganizationBody:
      type: object
      additionalProperties: false
      required:
        - name
        - typeId
      properties:
        name:
          type: string
          description: Organization name.
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        email:
          type: string
          format: email
          description: Primary work email for the organization.
          example: admissions@example.com
        phone:
          type: string
          description: Primary work phone for the organization.
          example: "555-555-5555"
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: "https://example.com"
        address:
          $ref: "#/components/schemas/PostOrganizationAddress"
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization.
        primaryContactId:
          type: string
          format: uuid
          description: Person to set as the organization's primary contact.
    PostOrganizationAddress:
      type: object
      properties:
        country:
          type: string
          example: US
        line:
          type: string
          description: Street address line 1.
          example: 123 Main St
        line2:
          type: string
          description: Street address line 2.
          example: Suite 100
        city:
          type: string
          example: New York
        region:
          type: string
          example: NY
        postalCode:
          type: string
          example: "10001"
        notes:
          type: string
          example: Main admissions office
    PostFacilityBody:
      type: object
      required:
        - name
        - nationalProviderId
        - phone
        - address
      properties:
        name:
          type: string
          description: Facility name.
          example: Ritten Recovery Center
        nationalProviderId:
          type: string
          description: National Provider Identifier (NPI)
          example: "1234567890"
        phone:
          type: string
          description: Primary facility phone number
          example: "555-555-5555"
        address:
          $ref: "#/components/schemas/PostFacilityAddress"
    PatchFacilityBody:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          description: Facility name. Leading and trailing whitespace is trimmed.
          example: Ritten Recovery Center
    PatchProgramBody:
      type: object
      additionalProperties: false
      minProperties: 1
      description: |
        Partial update body. At least one of name or facilityId must be provided.
        Omitted fields are left unchanged; programType and levelOfCare are not patchable.
      properties:
        name:
          type: string
          description: Program name. Leading and trailing whitespace is trimmed.
          example: Residential
        facilityId:
          type: string
          format: uuid
          description: Active facility ID to associate with the program.
    PostProgramBody:
      type: object
      additionalProperties: false
      description: |
        External create contract with a limited field set. Does not accept id; the server assigns the program ID on create.
      required:
        - name
        - programType
        - levelOfCare
      example:
        name: "Residential Treatment"
        programType: "Clinical"
        levelOfCare:
          - "Clinically Managed High-Intensity Residential Services (3.5)"
        facilityId: "182c2e54-3494-4b85-aba5-038cf539d5bf"
      properties:
        name:
          type: string
          description: Program name. Leading and trailing whitespace is trimmed.
          example: Residential
        facilityId:
          anyOf:
            - type: string
              format: uuid
            - type: "null"
          description: Optional active facility ID to associate with the program.
        programType:
          $ref: "#/components/schemas/ProgramType"
        levelOfCare:
          type: array
          minItems: 1
          uniqueItems: true
          description: |
            Exact catalog level-of-care values. Entries must be unique and compatible with programType
            (Clinical programs require clinical LOCs; Additional Service programs require non-clinical LOCs).
          items:
            $ref: "#/components/schemas/LevelOfCare"
    PatchOrganizationBody:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Organization name. Leading and trailing whitespace is trimmed.
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization.
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: "https://example.com"
    PostFacilityAddress:
      type: object
      required:
        - line
      properties:
        country:
          type: string
          description: Country code or name. US variants (e.g., "US", "USA", "United States") are normalized to "US".
          example: US
        line:
          type: string
          description: Street address line 1.
          example: 123 Main St
        line2:
          type: string
          description: Street address line 2.
          example: Suite 100
        city:
          type: string
          example: New York
        region:
          type: string
          description: For US addresses, must be a valid 2-letter US state/territory code or recognizable state name.
          example: NY
        postalCode:
          type: string
          example: "10001"
        timezone:
          type: string
          description: IANA timezone identifier.
          example: America/New_York
    PostCaseBody:
      type: object
      required:
        - caseName
      properties:
        caseName:
          type: string
          description: Name of the case (required)
          example: John Doe
        personSeekingTreatmentId:
          type: string
          format: uuid
          description: ID of the person seeking treatment
        caseOwnerId:
          type: string
          format: uuid
          description: ID of the staff member who owns this case
        contactIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of contacts associated with this case
        caseSource:
          type: string
          description: Name of the case source (must match an existing case source)
          example: Website
        caseSizeCents:
          type: integer
          minimum: 0
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          description: Potential admission date (ISO 8601)
          example: "2024-01-01T00:00:00Z"
        followUpDate:
          type: string
          format: date-time
          description: Follow-up date (ISO 8601)
          example: "2024-01-15T00:00:00Z"
        potentialProgramIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of potential programs for this case
        tags:
          type: array
          items:
            type: string
          description: Tag names to apply to the case (must match existing tags)
          example: ["urgent", "self-referral"]
        createdAt:
          type: string
          format: date-time
          description: Creation date (must be in the past, defaults to today if not provided)
          example: "2024-01-01T00:00:00Z"
    PatchCaseBody:
      type: object
      properties:
        caseName:
          type: string
          description: Name of the case
          example: John Doe
        personSeekingTreatmentId:
          type: string
          format: uuid
          description: ID of the person seeking treatment
        caseOwnerId:
          type: string
          format: uuid
          description: ID of the staff member who owns this case
        contactIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of contacts associated with this case (replaces existing)
        caseSource:
          type: string
          description: Name of the case source (must match an existing case source)
          example: Website
        caseSizeCents:
          type: integer
          minimum: 0
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          description: Potential admission date (ISO 8601)
          example: "2024-01-01T00:00:00Z"
        followUpDate:
          type: string
          format: date-time
          description: Follow-up date (ISO 8601)
          example: "2024-01-15T00:00:00Z"
        potentialProgramIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of potential programs for this case (replaces existing)
        tags:
          type: array
          items:
            type: string
          description: Tag names to apply to the case (replaces existing tags, must match existing tags)
          example: ["urgent", "self-referral"]
        createdAt:
          type: string
          format: date-time
          description: Creation date (must be in the past)
          example: "2024-01-01T00:00:00Z"
    Case:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseName:
          type: string
          example: John Doe
        status:
          type: string
          example: New
        caseSource:
          type: string
        caseSizeCents:
          type: integer
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        followUpDate:
          type: string
          format: date-time
          example: "2024-01-15T00:00:00Z"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        personSeekingTreatment:
          $ref: "#/components/schemas/CaseContact"
        caseOwner:
          $ref: "#/components/schemas/User"
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/CaseContact"
        potentialPrograms:
          type: array
          items:
            $ref: "#/components/schemas/Program"
        tags:
          type: array
          items:
            type: string
    PostCaseNoteBody:
      type: object
      required:
        - note
      properties:
        note:
          type: string
          description: The plain-text content of the note
          example: Patient called to confirm intake appointment
        userId:
          type: string
          format: uuid
          description: Optional ID of the user who wrote the note
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
    CaseNote:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseId:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        note:
          type: string
          example: Patient called to confirm intake appointment
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        owner:
          $ref: "#/components/schemas/User"
    PostCaseActionItemBody:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: The description of the action item
          example: Call the referral source to confirm insurance
    CaseActionItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseId:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        content:
          type: string
          example: Call the referral source to confirm insurance
        isComplete:
          type: boolean
          example: false
        completedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        completedBy:
          allOf:
            - $ref: "#/components/schemas/User"
          nullable: true
        createdAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
    Program:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        programName:
          type: string
          example: Residential
        programType:
          type: string
          example: clinical
    PatientName:
      type: object
      properties:
        first:
          type: string
          example: Doe
        middle:
          type: string
        last:
          type: string
          example: John
        pronouns:
          type: string
          example: "he/him"
        chosenName:
          type: string
          example: "Johnny"
    ListPatients:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 100
        patients:
          type: array
          items:
            $ref: "#/components/schemas/Patient"
    Patient:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        externalId:
          type: string
          description: An external identifier for the patient (e.g. an ID from a third-party system)
        dob:
          type: string
          description: date of birth
        createdAt:
          type: string
          format: date-time
          description: Patient record creation timestamp.
          example: "2024-01-01T00:00:00Z"
        mrn:
          type: string
          description: Ritten Medical Record Number
        name:
          $ref: "#/components/schemas/PatientName"
        programStatus:
          type: string
          enum:
            - prospective
            - active
        latestClinicalProgram:
          $ref: "#/components/schemas/PatientProgram"
        programs:
          type: array
          items:
            $ref: "#/components/schemas/PatientProgram"
        latestClinicalDischarge:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            dischargeType:
              type: string
        careTeam:
          type: object
          properties:
            id:
              type: string
            primaryClinicianId:
              type: string
            teamUserIds:
              type: array
              items:
                type: string
            primaryClinician:
              $ref: "#/components/schemas/User"
        phones:
          type: array
          description: Flattened phone contact point values. Primary phone numbers appear first when known; remaining values are ordered newest-first.
          items:
            type: string
            example: "+15555555555"
        emails:
          type: array
          description: Flattened email contact point values. Primary email addresses appear first when known; remaining values are ordered newest-first.
          items:
            type: string
            example: john@example.com
    PatientProgram:
      type: object
      properties:
        id:
          type: string
        program:
          type: object
          properties:
            id:
              type: string
            programName:
              type: string
            programType:
              type: string
              enum:
                - Clinical
                - Non-Clinical
        levelOfCare:
          type: string
        admitDate:
          type: string
        admittedByUserId:
          type: string
        estimatedDischargeDate:
          type: string
        dischargeTypeId:
          type: string
        dischargeDate:
          type: string
        transferredFrom:
          type: string
        transferredTo:
          type: string
    PatientDetail:
      allOf:
        - $ref: "#/components/schemas/Patient"
        - type: object
          properties:
            addresses:
              type: array
              items:
                $ref: "#/components/schemas/Address"
            diagnoses:
              type: array
              items:
                type: object
                properties:
                  diagnosis:
                    type: string
                  isPrimary:
                    type: boolean
            demographics:
              $ref: "#/components/schemas/PatientDemographics"
            referrals:
              type: array
              items:
                $ref: "#/components/schemas/Referral"
            insurance:
              type: array
              items:
                $ref: "#/components/schemas/Insurance"
    PatientDemographics:
      type: object
      properties:
        race:
          type: array
          items:
            type: string
            enum:
              - American Indian or Alaska Native
              - Asian
              - Black or African American
              - Native Hawaiian or Other Pacific Islander
              - White
              - Decline to Specify
        raceOther:
          type: array
          items:
            type: string
        ethnicity:
          type: array
          items:
            type: string
            enum:
              - Hispanic or Latino
              - Not Hispanic or Latino
              - Decline to Specify
        ethnicityOther:
          type: array
          items:
            type: string
        preferredLanguage:
          type: string
        sex:
          type: string
          enum:
            - Male
            - Female
            - Unknown
        gender:
          type: array
          items:
            type: string
            enum:
              - Male
              - Female
              - Transgender male
              - Transgender female
              - Genderqueer, neither exclusively male nor female
              - Decline to answer
              - Additional gender category, please specify.
        genderDetail:
          type: string
        sexualOrientation:
          type: string
          enum:
            - Straight or heterosexual
            - Lesbian, gay, or homosexual
            - Bisexual
            - Something else (please describe below)
            - Don’t know
            - Decline to Specify
        sexualOrientationDetail:
          type: string
        maritalStatus:
          type: string
          enum:
            - Married
            - Unmarried
            - Unknown
    Address:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        use:
          type: string
          enum:
            - HOME
            - WORK
            - OTHER
        country:
          type: string
          description: Country code or name. US variants (e.g., "US", "USA", "United States") are normalized to "US".
        line:
          type: string
        line2:
          type: string
        city:
          type: string
        region:
          type: string
          description: For US addresses, must be a valid 2-letter US state/territory code (e.g., "CA", "NY"). Common variants such as full state names and case variations are automatically normalized. For non-US addresses, accepts free-text state/province/region.
        postalCode:
          type: string
    Referral:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        referralTypeId:
          type: string
          description: The organization type ID of the referring organization
          example: 15b57ab4-9247-468e-85db-d86f7897207f
        organizationId:
          type: string
          description: The ID of the referring organization
          example: 66c2350d-a532-4d19-b063-24570269ef50
        personId:
          type: string
          description: The ID of the person who referred the patient
          example: e330e20b-b075-48c2-9432-c66a75c5d436
        isPrimary:
          type: boolean
    Insurance:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        payerId:
          type: string
          description: The ID of the insurance payer
          example: 15b57ab4-9247-468e-85db-d86f7897207f
        orderNumber:
          type: integer
        groupNumber:
          type: string
        memberIdentifier:
          type: string
        rxBIN:
          type: string
        rxPCN:
          type: string
        rxGroup:
          type: string
        startDate:
          type: string
        expirationDate:
          type: string
        notSubscriber:
          type: boolean
        comments:
          type: string
        providerPhoneNumber:
          type: string
        firstName:
          type: string
          description: The first name of the subscriber (if patient is not the subscriber)
        lastName:
          type: string
          description: The last name of the subscriber (if patient is not the subscriber)
        address:
          type: string
          description: The address of the subscriber (if patient is not the subscriber)
        city:
          type: string
          description: The city of the subscriber (if patient is not the subscriber)
        state:
          type: string
          description: The state of the subscriber (if patient is not the subscriber)
        postalCode:
          type: string
          description: The postal code of the subscriber (if patient is not the subscriber)
        subscriberPhoneNumber:
          type: string
          description: The phone number of the subscriber (if patient is not the subscriber)
        birthDate:
          type: string
          description: The birth date of the subscriber (if patient is not the subscriber)
          example: "1990-02-23"
        sex:
          type: string
          description: The sex of the subscriber (if patient is not the subscriber)
        relationship:
          description: The relationship of the subscriber to the patient
          $ref: "#/components/schemas/InsuranceRelationshipTypeEnum"
    ListContacts:
      type: array
      items:
        $ref: "#/components/schemas/Contact"
    Contact:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        first:
          type: string
          example: John
        middle:
          type: string
        last:
          type: string
          example: Doe
        dob:
          type: string
          description: Date of birth
          example: "1990-02-23"
        mrn:
          type: string
          description: Ritten Medical Record Number (if applicable)
        email:
          type: string
          description: The contact's primary email address. Falls back to their most recently added email when none is marked primary, and is omitted when they have none.
          example: john@example.com
        createdAt:
          type: string
          format: date-time
          description: Contact record creation timestamp.
          example: "2024-01-01T00:00:00Z"
        organizations:
          type: array
          description: Organizations this contact is associated with. Omitted when they belong to none.
          items:
            $ref: "#/components/schemas/ContactOrganization"
    CaseContact:
      type: object
      description: |
        A contact as it appears on a case. Deliberately narrower than the Contact returned by
        the /contacts endpoints: it carries identity only, with no email or organizations.
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        first:
          type: string
          example: John
        middle:
          type: string
        last:
          type: string
          example: Doe
        dob:
          type: string
          description: Always empty on this surface. Use GET /contacts/{id} for a contact's date of birth.
          example: ""
        mrn:
          type: string
          description: Ritten Medical Record Number (if applicable)
        createdAt:
          type: string
          format: date-time
          description: Contact record creation timestamp.
          example: "2024-01-01T00:00:00Z"
    ContactOrganization:
      type: object
      description: An organization a contact is associated with.
      properties:
        id:
          type: string
          format: uuid
          description: The organization's ID. Pass to GET /organizations/{id} for the full record.
          example: 9a5e64b0-0a73-4cb5-ab32-44fea16da4e1
        name:
          type: string
          example: Sunrise Recovery Center
        relationshipType:
          type: string
          description: How the contact relates to the organization. Omitted when unset.
          example: member
        isPrimary:
          type: boolean
          description: Whether this is the contact's primary organization.
    ContactDetail:
      allOf:
        - $ref: "#/components/schemas/Contact"
        - type: object
          properties:
            contactPoints:
              type: array
              items:
                $ref: "#/components/schemas/ContactPoint"
            address:
              $ref: "#/components/schemas/Address"
    ContactPoint:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        system:
          type: string
          enum:
            - PHONE
            - EMAIL
            - FAX
        use:
          type: string
          enum:
            - HOME
            - WORK
            - MOBILE
            - PERSONAL
        value:
          type: string
        valueExt:
          type: string
          description: Extension for phone numbers
        isPrimary:
          type: boolean
        notes:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        email:
          type: string
          example: johndoe@ritclinic.ritten.io
        first:
          type: string
          example: Doe
        middle:
          type: string
        last:
          type: string
          example: John
        lastAccessedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the user's most recent app session start (set when the user loads the app). Null if the user has never logged in.
          example: "2024-01-15T14:32:00Z"
    ContactRelationship:
      type: object
      properties:
        personId:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        type:
          type: string
          description: The type of relationship
    PatientRelationship:
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        - $ref: "#/components/schemas/ContactRelationship"
        - type: object
          properties:
            isEmergencyContact:
              type: boolean
            isGuarantor:
              type: boolean
            isGuardian:
              type: boolean
    DocumentTypeEnum:
      type: string
      enum:
        - Pre-Admission
        - Lab/Toxicology Results
        - Nursing Shift Notes
        - Release of Information
        - Consent
        - Waiver
        - Policy and Procedure
        - Homework
        - Medical Record
        - Insurance Card
        - Client Photo
        - Other
        - Prescriptions
        - Consults
        - Psych Testing
        - Correspondence
        - Intake
        - Authorization
    ClinicTeam:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        name:
          type: string
          example: "Cool Team"
        userIds:
          type: array
          items:
            type: string
            example: f87e1b07-1d20-4c36-8c37-08600daf7322
    IDSchema:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
    CalendarEventCore:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        title:
          type: string
          example: Therapy Appointment
        description:
          type: string
        location:
          type: string
        startTime:
          type: string
          example: "2024-02-13T13:00:00-05:00"
        endTime:
          type: string
          example: "2024-02-13T13:00:00-05:00"
    CalendarEventInterval:
      type: [string, "null"]
      enum:
        - 0m
        - 15m
        - 30m
        - 1h
        - 24h
        - 2d
        - 3d
    CalendarEvent:
      allOf:
        - $ref: "#/components/schemas/CalendarEventCore"
        - type: object
          properties:
            frequency:
              type: string
              enum:
                - day
                - week
                - month
                - yeah
                - custom
            interval:
              $ref: "#/components/schemas/CalendarEventInterval"
            daysOfWeek:
              type: array
              items:
                type: string
                enum:
                  - Monday
                  - Tuesday
                  - Wednesday
                  - Thursday
                  - Friday
                  - Saturday
                  - Sunday
            until:
              type: [string, "null"]
              example: "2024-02-13T13:00:00-05:00"
    Payer:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        payerIdentifier:
          type: string
        payerGroupId:
          type: string
          example: 15b57ab4-9247-468e-85db-d86f7897207f
        name:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        notes:
          type: string
    InsuranceRelationshipTypeEnum:
      type: string
      enum:
        - The Beneficiary is a child of the Subscriber
        - Parent
        - Spouse
        - Common-Law Spouse
        - Other
        - Self
        - Injured Party
    AdmissionsReport:
      type: object
      properties:
        admissions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: "Admit"
              admitDate:
                type: string
                format: date-time
              dischargeDate:
                type: [string, "null"]
                format: date-time
              program:
                type: string
              programId:
                type: string
                format: uuid
                description: Clinic program ID corresponding to the program name
              levelOfCare:
                type: string
              referralType:
                type: string
              referralOrganization:
                type: string
              referralPointOfContact:
                type: string
              mrn:
                type: string
              name:
                type: string
              age:
                type: integer
              sex:
                type: string
              notes:
                type: string
              primaryClinician:
                type: string
              phoneUse:
                type: string
              phoneNumber:
                type: string
              addressUse:
                type: string
              addressLine:
                type: string
              addressLine2:
                type: string
              addressCity:
                type: string
              addressRegion:
                type: string
              addressCountry:
                type: string
              addressPostalCode:
                type: string
              email:
                type: string
              notify:
                type: boolean
              portalEmail:
                type: string
              programLos:
                type: integer
                description: Length of stay in days
              payerName:
                type: string
              insuranceStartDate:
                type: [string, "null"]
                format: date
              insuranceExpirationDate:
                type: [string, "null"]
                format: date
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        clinicURL:
          type: string
        clinical:
          type: boolean
    DischargesReport:
      type: object
      properties:
        discharges:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              dischargeName:
                type: string
              admitDate:
                type: string
                format: date-time
              dischargeDate:
                type: string
                format: date-time
              program:
                type: string
              programId:
                type: string
                description: Clinic program ID corresponding to the program name. When combineTransfers=true, this is a comma-delimited list aligned with the comma-delimited program value.
              transferToProgram:
                type: string
              levelOfCare:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              age:
                type: integer
              sex:
                type: string
              notes:
                type: string
              los:
                type: integer
                description: Length of stay in days
              primaryClinician:
                type: string
              email:
                type: string
              notify:
                type: boolean
              portalEmail:
                type: string
        combineTransfers:
          type: boolean
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        clinicURL:
          type: string
        clinical:
          type: boolean
    AlosReport:
      type: object
      properties:
        aloss:
          type: array
          items:
            type: object
            properties:
              clientFirstName:
                type: string
              clientLastName:
                type: string
              currentStatus:
                type: string
              age:
                type: integer
              sex:
                type: string
              current:
                type: string
                description: X if currently in program
              program:
                type: string
              programType:
                type: string
              programLoc:
                type: string
              programLos:
                type: integer
                description: Length of stay in days
              admitDate:
                type: string
                format: date-time
              dischargeDate:
                type: [string, "null"]
                format: date-time
              primaryClinician:
                type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
    ProgramCensusReport:
      type: object
      properties:
        censuses:
          type: array
          items:
            type: object
            properties:
              programId:
                type: string
                format: uuid
              program:
                type: string
              programLoc:
                type: array
                items:
                  type: string
              average:
                type: number
                description: Average daily census
              startCount:
                type: integer
                description: Beginning census
              endCount:
                type: integer
                description: Ending census
              minCount:
                type: integer
                description: Minimum census during period
              maxCount:
                type: integer
                description: Maximum census during period
              archived:
                type: boolean
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
    CensusReport:
      type: object
      properties:
        patients:
          type: array
          items:
            type: object
            properties:
              clientFirstName:
                type: string
              clientLastName:
                type: string
              mrn:
                type: string
              dob:
                type: [string, "null"]
                format: date
              age:
                type: integer
              clinicalProgramNames:
                type: array
                items:
                  type: string
              levelsOfCare:
                type: array
                items:
                  type: string
              nonClinicalProgramNames:
                type: array
                items:
                  type: string
              originalAdmitDate:
                type: string
                format: date-time
              estimatedDischargeDates:
                type: [string, "null"]
                format: date
              teamNames:
                type: array
                items:
                  type: string
              primaryEmail:
                type: string
              primaryPhone:
                type: string
              race:
                type: array
                items:
                  type: string
              ethnicity:
                type: array
                items:
                  type: string
              preferredLanguage:
                type: string
              sex:
                type: string
              gender:
                type: array
                items:
                  type: string
              sexuality:
                type: string
              maritalStatus:
                type: string
              payerType:
                type: string
              payerName:
                type: string
              insuranceStartDate:
                type: [string, "null"]
                format: date
              insuranceExpirationDate:
                type: [string, "null"]
                format: date
              primaryClinicianFirst:
                type: string
              primaryClinicianLast:
                type: string
              diagnoses:
                type: array
                items:
                  type: string
              allergies:
                type: array
                items:
                  type: string
              billingAddressUse:
                type: string
              billingAddressCountry:
                type: string
              billingAddressLine:
                type: string
              billingAddressLine2:
                type: string
              billingAddressCity:
                type: string
              billingAddressRegion:
                type: string
              billingAddressPostalCode:
                type: string
              billingAddressNotes:
                type: string
              emergencyContactName:
                type: string
              emergencyContactPhone:
                type: string
              emergencyContactEmail:
                type: string
        isBrief:
          type: boolean
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
    DbsReport:
      type: object
      properties:
        dbss:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              serviceDate:
                type: string
                format: date
              patientID:
                type: string
                format: uuid
              firstName:
                type: string
              lastName:
                type: string
              dob:
                type: [string, "null"]
                format: date
              mrn:
                type: string
              diagnoses:
                type: array
                items:
                  type: string
              program:
                type: string
              programLoc:
                type: string
              facilityName:
                type: string
              fundingSource:
                type: string
              payerGroup:
                type: string
              procedureCode:
                type: string
              procedureCodeModifiers:
                type: array
                items:
                  type: string
              addOnCodes:
                type: array
                items:
                  type: string
              addOnBilledAmountTotal:
                type: number
              addOnAllowedAmountTotal:
                type: number
              revenueCode:
                type: string
              placeOfServiceCode:
                type: string
              isBundled:
                type: boolean
              minimumBundledMinutes:
                type: integer
              associated_encounters:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    type:
                      type: string
                    encounterTemplateId:
                      type: string
                      format: uuid
                    patientId:
                      type: string
                      format: uuid
                    status:
                      type: string
                    startTime:
                      type: string
                      format: date-time
                    endTime:
                      type: [string, "null"]
                      format: date-time
                    attendanceType:
                      type: string
                    createdAt:
                      type: string
                      format: date-time
                    deletedAt:
                      type: [string, "null"]
                      format: date-time
                    groupEncounterId:
                      type: [string, "null"]
                      format: uuid
                    totalBillableMinutes:
                      type: integer
              billedRate:
                type: number
              expectedRate:
                type: number
              unitsTotal:
                type: integer
              claimStatus:
                type: string
              provider:
                type: string
              primaryPayerGroup:
                type: string
              primaryPayerName:
                type: string
              authStartDate:
                type: [string, "null"]
                format: date
              authEndDate:
                type: [string, "null"]
                format: date
              authBilledUnits:
                type: integer
              authUsedUnits:
                type: integer
              authRemainingUnits:
                type: integer
              authTrackingNumber:
                type: string
              authProcedureCodes:
                type: array
                items:
                  type: string
              authDiagnosis:
                type: string
              authPayerName:
                type: string
              authPayerID:
                type: [string, "null"]
                format: uuid
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        clinicURL:
          type: string
    EventAuditReport:
      type: object
      properties:
        eventAudits:
          type: array
          items:
            type: object
            properties:
              eventId:
                type: string
                format: uuid
              eventName:
                type: string
              eventEncounter:
                type: string
                description: Encounter type name
              startTime:
                type: string
                format: date-time
              minutesAttended:
                type: number
              isGroup:
                type: boolean
              staff:
                type: array
                items:
                  type: object
                  properties:
                    uuid:
                      type: string
                    name:
                      type: string
                  required:
                    - uuid
                    - name
                description: Staff attendee names
              clients:
                type: array
                items:
                  type: object
                  properties:
                    uuid:
                      type: string
                    name:
                      type: string
                    mrn:
                      type: string
                    type:
                      type: string
                      enum:
                        - patient
                        - program
                        - clinic team
                  required:
                    - uuid
                    - name
                    - type
                description: Client attendee names
              status:
                type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
    OrganizationsReport:
      type: object
      properties:
        organizations:
          type: array
          items:
            type: object
            properties:
              orgName:
                type: string
              orgType:
                type: string
              url:
                type: string
              relationshipOwner:
                type: string
              primaryContact:
                type: string
              email:
                type: string
              phone:
                type: string
              addressLine:
                type: string
              addressLine2:
                type: string
              addressCity:
                type: string
              addressRegion:
                type: string
              addressCountry:
                type: string
              addressPostalCode:
                type: string
              memberCount:
                type: [integer, "null"]
    OrganizationNotesReport:
      type: object
      properties:
        organizationNoteSet:
          type: object
          properties:
            notes:
              type: array
              items:
                type: object
                properties:
                  organizationId:
                    type: string
                    format: uuid
                  organizationName:
                    type: string
                  primaryContactName:
                    type: string
                  noteTakenAt:
                    type: [string, "null"]
                    format: date-time
                  noteActivityType:
                    type: string
                  noteContent:
                    type: string
                  creator:
                    type: string
            startDate:
              type: string
              format: date-time
            endDate:
              type: string
              format: date-time
            clinicURL:
              type: string
    CreatedCasesReport:
      type: object
      properties:
        deals:
          type: array
          items:
            type: object
            properties:
              dealId:
                type: string
                format: uuid
              dealName:
                type: string
              createdAt:
                type: string
                format: date-time
              dealStatus:
                type: string
              caseSource:
                type: string
              dealOwner:
                type: string
              personSeekingTreatment:
                type: string
              dealContactNames:
                type: string
              referralPointOfContact:
                type: string
              referralOrganizations:
                type: string
              referralOrganizationRelationshipOwners:
                type: string
              referralType:
                type: string
              potentialAdmitDate:
                type: [string, "null"]
                format: date-time
              dealSize:
                type: integer
                description: In cents
              anticipatedPrograms:
                type: array
                items:
                  type: string
              admittedDate:
                type: [string, "null"]
                format: date-time
              fundingSource:
                type: string
              payerGroupName:
                type: string
              payerName:
                type: string
        clinicURL:
          type: string
    DisqualifiedCasesReport:
      type: object
      properties:
        deals:
          type: array
          items:
            type: object
            properties:
              dealId:
                type: string
                format: uuid
              dealName:
                type: string
              dealDisqualificationDate:
                type: string
                format: date-time
              createdAt:
                type: string
                format: date-time
              personSeekingTreatment:
                type: string
              dealContactNames:
                type: string
              referralPointOfContact:
                type: string
              referralOrganization:
                type: string
              referralOrganizationRelationshipOwners:
                type: string
              referralType:
                type: string
              dealSize:
                type: integer
                description: In cents
              anticipatedPrograms:
                type: array
                items:
                  type: string
              referralSource:
                type: string
              caseSource:
                type: string
              dealOwner:
                type: string
              fundingSource:
                type: string
              payerGroupName:
                type: string
              payerName:
                type: string
              disqualificationReason:
                type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        clinicURL:
          type: string
    CareTeamsReport:
      type: object
      properties:
        careTeams:
          type: array
          items:
            type: object
            properties:
              firstName:
                type: string
              lastName:
                type: string
              mrn:
                type: string
              activeClinicalProgram:
                type: string
                description: Active clinical program name with level of care
              admitDate:
                type: [string, "null"]
                format: date-time
              activeAdditionalServices:
                type: string
                description: Pipe-separated list of additional services
              payer:
                type: string
              primaryClinician:
                type: string
              primaryClinicianRoles:
                type: string
                description: Comma-separated list of roles
              clinician2Name:
                type: string
              clinician2Roles:
                type: string
              clinician3Name:
                type: string
              clinician3Roles:
                type: string
              clinician4Name:
                type: string
              clinician4Roles:
                type: string
              clinician5Name:
                type: string
              clinician5Roles:
                type: string
              clinician6Name:
                type: string
              clinician6Roles:
                type: string
              clinician7Name:
                type: string
              clinician7Roles:
                type: string
              clinician8Name:
                type: string
              clinician8Roles:
                type: string
              clinician9Name:
                type: string
              clinician9Roles:
                type: string
              clinician10Name:
                type: string
              clinician10Roles:
                type: string
    EncounterHistoryReport:
      type: object
      properties:
        encounters:
          type: array
          items:
            type: object
            properties:
              encounterID:
                type: string
                format: uuid
              patientID:
                type: string
                format: uuid
              firstName:
                type: string
              lastName:
                type: string
              mrn:
                type: string
              program:
                type: string
                description: Current clinical program name
              programLoc:
                type: string
                description: Level of care
              encounterType:
                type: string
              isGroup:
                type: boolean
              isBilling:
                type: boolean
              encounterCreator:
                type: string
              supervisingProvider:
                type: string
              status:
                type: string
                enum: [Pending, In Progress, Scheduled, Complete, Incomplete, Cancelled]
              startTime:
                type: string
                format: date-time
              endTime:
                type: [string, "null"]
                format: date-time
              attendanceType:
                type: string
              fundingSource:
                type: string
              primaryInsurancePayer:
                type: string
              minutesAttended:
                type: number
              groupEncounterID:
                type: [string, "null"]
                format: uuid
              groupTitle:
                type: string
              modifiers:
                type: array
                items:
                  type: string
              completedForms:
                type: integer
              incompleteForms:
                type: integer
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        clinicURL:
          type: string
        supervisingProvidersEnabled:
          type: boolean

    ClientEventHistoryReport:
      type: object
      properties:
        Events:
          type: array
          items:
            type: object
            properties:
              Date:
                type: string
                format: date-time
              EventName:
                type: string
              StartTime:
                type: string
                format: date-time
              EndTime:
                type: string
                format: date-time
              TotalDuration:
                type: number
                description: Duration in minutes
              Status:
                type: string
                description: Event status (Occurred, Scheduled, Canceled, OccurredNoEncounter)
              AttendanceType:
                type: string
              Absent:
                type: boolean
              Billable:
                type: boolean
              BillableUnits:
                type: integer
              CancellationType:
                type: string
              Note:
                type: string
              PatientID:
                type: string
                format: uuid
              FirstName:
                type: string
              LastName:
                type: string
              ProgramName:
                type: string
              LevelOfCare:
                type: string
              EncounterType:
                type: string
              IsGroup:
                type: boolean
        StartDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time

    ClientAttendanceByStatusReport:
      type: object
      properties:
        rows:
          type: array
          items:
            type: object
            properties:
              firstName:
                type: string
              lastName:
                type: string
              programName:
                type: string
              levelOfCare:
                type: string
              encounterType:
                type: string
              billable:
                type: boolean
              isGroup:
                type: boolean
              statusCounts:
                type: object
                additionalProperties:
                  type: integer
                description: Map of attendance type name to count
              minutesAttended:
                type: number
              totalBillableUnits:
                type: integer
        attendanceTypes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              absent:
                type: boolean
              billable:
                type: boolean
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time

    FormOutcomesReport:
      type: object
      required:
        - outcomes
        - formName
        - startDate
        - endDate
      properties:
        outcomes:
          type: array
          items:
            type: object
            required:
              - mrn
              - firstName
              - lastName
              - formInstanceId
              - formCreatedAt
            properties:
              mrn:
                type: string
                description: Patient medical record number
              firstName:
                type: string
              lastName:
                type: string
              clientStatus:
                type: string
                description: Patient status (e.g., Active, Discharged)
              episodeAdmitDate:
                type: string
                format: date-time
              program:
                type: string
                description: Clinical program name
              levelOfCare:
                type: string
              additionalServices:
                type: string
              serviceEnrollmentDate:
                type: string
              los:
                type: integer
                description: Length of stay in days
              encounterType:
                type: string
              encounterStartTime:
                type: string
                format: date-time
              formInstanceId:
                type: string
                format: uuid
              formCreatedAt:
                type: string
                format: date-time
              formCreatedByFirst:
                type: string
                description: First name of user who created the form
              formCreatedByLast:
                type: string
                description: Last name of user who created the form
              fieldData:
                type: object
                additionalProperties:
                  type: string
                description: Map of field definition IDs to field values
        formName:
          type: string
          description: Name of the form definition
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time

    FormDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
          description: Internal label for the form
        title:
          type: string
          description: Display title of the form
        description:
          type: string
        instructions:
          type: object
          properties:
            plainText:
              type: string
            richText:
              type: string
          description: Form instructions in plain text and rich text formats
        isPatientEligible:
          type: boolean
          description: Whether patients can fill out this form
        isTxPlanForm:
          type: boolean
          description: Whether this is a treatment plan form
        txPlanCategoryId:
          type: string
          format: uuid
          nullable: true
          description: Treatment plan category ID if applicable
        newFormNeededInXDays:
          type: integer
          description: Number of days after which a new form instance is needed
        archiveDueFormsOnDischarge:
          type: boolean
          description: Whether to archive due forms when patient is discharged
        sectionDefinitions:
          type: array
          items:
            $ref: "#/components/schemas/SectionDefinition"
        signatureRequirements:
          type: array
          items:
            $ref: "#/components/schemas/FormDefinitionSignatureRequirement"

    SectionDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        title:
          type: string
        description:
          type: string
        sortOrder:
          type: integer
        fieldDefinitions:
          type: array
          items:
            $ref: "#/components/schemas/FieldDefinition"

    FieldDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        title:
          type: string
        description:
          type: string
        fieldType:
          type: string
          description: Type of field (e.g., text, number, date, select)
        sortOrder:
          type: integer
        isRequired:
          type: boolean
        options:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
          description: Options for select/radio/checkbox fields

    FormDefinitionSignatureRequirement:
      type: object
      properties:
        id:
          type: string
          format: uuid
        formDefinitionId:
          type: string
          format: uuid
        roles:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
          description: Roles that can fulfill this signature requirement