Tebra Clinical Data API

openapi: 3.0.3
info:
  title: Tebra Clinical Data API
  description: >-
    Read-only REST access to a patient's clinical health information held in the
    Tebra (formerly Kareo + PatientPop) platform. This is Tebra's ONC / 21st
    Century Cures Act "patient access" API surface (published under
    tebra.com/macra), exposing USCDI-aligned clinical resources for a single
    authenticated patient. Every request is authenticated with an API Key passed
    in the `X-Api-Key` header; the key is generated by the patient from the Tebra
    Patient Portal under My Account > API Access Key. Connections must use HTTPS
    (TLS) and callers are asked to limit connection frequency to what their use
    case requires.

    The resource paths and the X-Api-Key authentication in this document are
    confirmed from Tebra's official "General API Documentation" (Oct 2023). The
    request query parameters and response schemas below are MODELED to reflect
    typical USCDI / FHIR-flavored patient-access payloads and should be verified
    against the current Tebra API documentation before production use.
  version: '1.0'
  contact:
    name: Tebra
    url: https://www.tebra.com/macra
  license:
    name: Proprietary (Tebra API Terms of Use)
    url: https://www.tebra.com
servers:
  - url: https://api.tebra.com/clinical/v1/api
    description: Tebra Clinical Data API (production)
security:
  - apiKeyAuth: []
tags:
  - name: Patient
    description: Core patient demographic record.
  - name: Clinical
    description: USCDI-aligned clinical data classes for the authenticated patient.
  - name: Documents
    description: Binary clinical summary documents (e.g. C-CDA).
paths:
  /patient:
    get:
      tags:
        - Patient
      summary: Get patient
      description: >-
        Retrieves the demographic record for the patient associated with the
        supplied API Key. Confirmed endpoint; response fields are modeled.
      operationId: getPatient
      responses:
        '200':
          description: Patient record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/allergyIntolerance/medication:
    get:
      tags:
        - Clinical
      summary: Get medication allergies and intolerances
      description: >-
        Retrieves allergy and intolerance records associated with the patient.
        Confirmed endpoint; response is modeled as a USCDI AllergyIntolerance list.
      operationId: getAllergyIntolerance
      responses:
        '200':
          description: Allergy / intolerance list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/carePlan:
    get:
      tags:
        - Clinical
      summary: Get care plan
      description: Retrieves care plan entries for the patient. Confirmed endpoint; response modeled.
      operationId: getCarePlan
      responses:
        '200':
          description: Care plan list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/condition/problemList:
    get:
      tags:
        - Clinical
      summary: Get problem list conditions
      description: Retrieves problem-list conditions for the patient. Confirmed endpoint; response modeled.
      operationId: getProblemList
      responses:
        '200':
          description: Condition list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/device:
    get:
      tags:
        - Clinical
      summary: Get implantable devices
      description: Retrieves device records associated with the patient. Confirmed endpoint; response modeled.
      operationId: getDevice
      responses:
        '200':
          description: Device list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/diagnosticReport:
    get:
      tags:
        - Clinical
      summary: Get diagnostic reports
      description: Retrieves diagnostic report records for the patient. Confirmed endpoint; response modeled.
      operationId: getDiagnosticReport
      responses:
        '200':
          description: Diagnostic report list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/encounter:
    get:
      tags:
        - Clinical
      summary: Get encounters
      description: Retrieves encounter records associated with the patient. Confirmed endpoint; response modeled.
      operationId: getEncounter
      responses:
        '200':
          description: Encounter list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/goal:
    get:
      tags:
        - Clinical
      summary: Get goals
      description: Retrieves care goals for the patient. Confirmed endpoint; response modeled.
      operationId: getGoal
      responses:
        '200':
          description: Goal list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/immunization:
    get:
      tags:
        - Clinical
      summary: Get immunizations
      description: Retrieves immunization records for the patient. Confirmed endpoint; response modeled.
      operationId: getImmunization
      responses:
        '200':
          description: Immunization list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/medicationStatement:
    get:
      tags:
        - Clinical
      summary: Get medications
      description: Retrieves medication statement records for the patient. Confirmed endpoint; response modeled.
      operationId: getMedicationStatement
      responses:
        '200':
          description: Medication statement list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/observation/vitalSigns:
    get:
      tags:
        - Clinical
      summary: Get vital signs
      description: Retrieves vital sign observations for the patient. Confirmed endpoint; response modeled.
      operationId: getVitalSigns
      responses:
        '200':
          description: Vital sign observation list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/procedure:
    get:
      tags:
        - Clinical
      summary: Get procedures
      description: Retrieves procedure records for the patient. Confirmed endpoint; response modeled.
      operationId: getProcedure
      responses:
        '200':
          description: Procedure list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/smokingStatus:
    get:
      tags:
        - Clinical
      summary: Get smoking status
      description: Retrieves the patient's smoking status observation. Confirmed endpoint; response modeled.
      operationId: getSmokingStatus
      responses:
        '200':
          description: Smoking status observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/binary/summary:
    get:
      tags:
        - Documents
      summary: Get clinical summary document
      description: >-
        Retrieves the patient's clinical summary as a binary document
        (e.g. a C-CDA). Confirmed endpoint; response modeled.
      operationId: getBinarySummary
      responses:
        '200':
          description: Binary clinical summary document.
          content:
            application/xml:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Patient-generated API Key from the Tebra Patient Portal
        (My Account > API Access Key). A missing, revoked, or invalid key
        returns 401 Unauthorized.
  responses:
    Unauthorized:
      description: The API Key is missing, revoked, or otherwise not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Patient:
      type: object
      description: Patient demographic record (modeled).
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        gender:
          type: string
    ResourceList:
      type: object
      description: >-
        Generic container for a list of USCDI-aligned clinical resources
        (modeled). Actual payloads follow Tebra's clinical data format.
      properties:
        resourceType:
          type: string
        entry:
          type: array
          items:
            type: object
            additionalProperties: true
    Error:
      type: object
      properties:
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Unauthorized