Ritten Insights API

openapi: 3.2.0
info:
  title: External Insights API
  x-logo:
    url: https://storage.googleapis.com/ritten-ops-public-logos/rittenBanner
    backgroundColor: '#FFFFFF'
    altText: Ritten Logo
  description: "For Ritten Integrating Partners\n\n## Authentication\n\n- Request an access token with your provided integration credentials (`client_id` and `client_secret`) by calling our token endpoint:\n```bash\ncurl https://api.ritten.io/v1/oauth/token \\\n  -X POST \\\n  -H 'content-type: application/json' \\\n  -d '{\"client_id\":\"${client_id}\",\"client_secret\":\"${client_secret}\",\"audience\":\"https://external-api.ritten.io\",\"grant_type\":\"client_credentials\"}'\n```\n- Take the `access_token` from the response and use that as the `Bearer` token in your requests to our API.\n- 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.\n- The token endpoint itself does not require a Bearer token; the `client_secret` in the body is the authentication.\n\n> **Note:** When working in non-production environments, the API endpoints (and `audience` value) will be different.\n> For example, in the `beta` environment, the token endpoint is `https://api.beta.ritten.io/v1/oauth/token`\n> and the audience is `https://external-api.beta.ritten.io`.\n\n## Tenant Header\n\n- Make sure to add the tenant ID to the header of every request. This is the Ritten Clinic instance the request will target. Example:\n```\nX-Ritten-Tenant: ritclinic\n```\n\n## Rate Limiting\n\nTwo layers of rate limiting apply: per-request limits on API calls, and per-app limits on token minting.\n\n### API request rate limit\n\nApplied to authenticated API calls (everything except `/v1/oauth/token`):\n\n- 50 requests per second sustained rate\n- 100 requests burst allowance\n\nYou 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.\n\n### Token mint quota (Auth0)\n\nA separate per-application limit on how often you can mint new access tokens:\n\n- 2 mints per hour\n- 3 mints per day\n\nThese 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.\n\nToken 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.\n"
  version: 1.0.0
servers:
- url: https://api.ritten.io/v1
tags:
- 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.

    '
paths:
  /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
components:
  schemas:
    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
    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
    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

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ritten/refs/heads/main/openapi/ritten-insights-api-openapi.yml