openapi: 3.0.3
info:
  title: Tebra FHIR API
  description: >-
    SMART on FHIR (HL7 FHIR R4) read access to a patient's clinical health
    information held in the Tebra (formerly Kareo) platform, built on the US
    Core Implementation Guide STU3 Release 3.1.1 and satisfying USCDI v1 / ONC
    21st Century Cures Act information-blocking requirements. Tebra has
    elected to partner with SmileCDR, a third-party FHIR services provider,
    to host this API; developers register applications through the appSphere
    developer portal and accept SmileCDR's terms at registration.

    All paths, the production/authorization/FHIR base URLs, the resource +
    parameter table, and the error code table are CONFIRMED verbatim from
    Tebra's official "Fast Healthcare Interoperability Resources (FHIR) API
    User Guide" (Updated May 2025), and from a live probe of
    fhir.prd.cloud.tebra.com on 2026-08-14 (401 Unauthorized on every resource
    GET without a token; 302 redirect on /smartauth/oauth/authorize; 401 on
    POST /smartauth/oauth/token). Response bodies are standard FHIR R4
    resources/Bundles per the referenced US Core profiles and are represented
    here generically (FHIRResource / FHIRBundle) rather than fully modeled,
    since Tebra's guide documents request shape and required search
    parameters but not full response payload schemas.
  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/wp-content/uploads/2025/05/Tebra-FHIR-API-User-Guide.pdf
servers:
- url: https://fhir.prd.cloud.tebra.com/fhir-request
  description: Tebra FHIR API (production, confirmed live)
security:
- smartOnFhirAuthCode: []
- smartOnFhirClientCredentials: []
tags:
- name: Patient
- name: AllergyIntolerance
- name: CarePlan
- name: CareTeam
- name: Condition
- name: DiagnosticReport
- name: DocumentReference
- name: Encounter
- name: Goal
- name: Immunization
- name: Device
- name: Observation
- name: Location
- name: Medication
- name: MedicationRequest
- name: Organization
- name: Practitioner
- name: PractitionerRole
- name: Procedure
- name: Provenance
paths:
  /Patient:
    get:
      tags: [Patient]
      summary: Get patient
      description: Retrieves a patient. Confirmed endpoint (US Core Patient Profile).
      operationId: getPatient
      parameters:
      - name: id
        in: query
        required: true
        description: The id of the patient.
        schema: { type: string }
      - name: identifier
        in: query
        required: false
        description: Identifier such as a MPI.
        schema: { type: string }
      - name: name
        in: query
        required: false
        description: Match any part of the name.
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /AllergyIntolerance:
    get:
      tags: [AllergyIntolerance]
      summary: Get allergy intolerance
      description: Retrieves allergies/adverse reactions for a patient. Confirmed endpoint (US Core AllergyIntolerance Profile).
      operationId: getAllergyIntolerance
      parameters:
      - name: patient
        in: query
        required: true
        description: All allergy and intolerances for a patient.
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /CarePlan:
    get:
      tags: [CarePlan]
      summary: Get care plan
      description: Retrieves assessment and plan of treatment for a patient. Confirmed endpoint (US Core CarePlan Profile).
      operationId: getCarePlan
      parameters:
      - name: patient
        in: query
        required: true
        description: All CarePlan resources by category (patient + category).
        schema: { type: string }
      - name: category
        in: query
        required: true
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /CareTeam:
    get:
      tags: [CareTeam]
      summary: Get care team
      description: Retrieves persons who participate in a patient's care. Confirmed endpoint (US Core CareTeam Profile).
      operationId: getCareTeam
      parameters:
      - name: patient
        in: query
        required: true
        description: All members of care team for patients of an identified status (patient + status).
        schema: { type: string }
      - name: status
        in: query
        required: true
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Condition:
    get:
      tags: [Condition]
      summary: Get condition
      description: Retrieves problems, health concerns, and encounter diagnosis. Confirmed endpoint (US Core Condition Profile).
      operationId: getCondition
      parameters:
      - name: patient
        in: query
        required: true
        description: All condition resources for a patient.
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /DiagnosticReport:
    get:
      tags: [DiagnosticReport]
      summary: Get diagnostic report
      description: Retrieves lab tests/results and report/note DiagnosticReport resources for a patient. Confirmed endpoint (US Core DiagnosticReport profiles for Lab Results and Report/Note Exchange).
      operationId: getDiagnosticReport
      parameters:
      - name: patient
        in: query
        required: true
        description: All DiagnosticReport results.
        schema: { type: string }
      - name: category
        in: query
        required: false
        description: 'DiagnosticReport results identified by a category code (e.g. LP29684-5 for all radiology reports).'
        schema: { type: string }
      - name: code
        in: query
        required: false
        description: 'DiagnosticReport results with a specific code (e.g. 24323-8 for CMP).'
        schema: { type: string }
      - name: date
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /DocumentReference:
    get:
      tags: [DocumentReference]
      summary: Get document reference
      description: Retrieves patient documents, including clinical notes. Confirmed endpoint (US Core DocumentReference Profile).
      operationId: getDocumentReference
      parameters:
      - name: id
        in: query
        required: false
        description: The id of a single document.
        schema: { type: string }
      - name: patient
        in: query
        required: true
        description: All documents for a specific patient.
        schema: { type: string }
      - name: category
        in: query
        required: false
        description: 'All documents identified by a category code (e.g. clinical-note).'
        schema: { type: string }
      - name: type
        in: query
        required: false
        description: 'All documents for a specific patient and type (e.g. 18842-5 for a discharge summary).'
        schema: { type: string }
      - name: date
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Encounter:
    get:
      tags: [Encounter]
      summary: Get encounter
      description: Retrieves basic encounter information for a patient.
      operationId: getEncounter
      parameters:
      - name: id
        in: query
        required: false
        schema: { type: string }
      - name: patient
        in: query
        required: true
        description: All encounter information for a specific patient.
        schema: { type: string }
      - name: date
        in: query
        required: false
        description: All encounter information for a specific patient on a specific date (date + patient).
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Goal:
    get:
      tags: [Goal]
      summary: Get goal
      description: Retrieves all goal information for a patient. Confirmed endpoint (US Core Goal Profile).
      operationId: getGoal
      parameters:
      - name: patient
        in: query
        required: true
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Immunization:
    get:
      tags: [Immunization]
      summary: Get immunization
      description: Retrieves immunization history for a patient. Confirmed endpoint (US Core Immunizations Profile).
      operationId: getImmunization
      parameters:
      - name: patient
        in: query
        required: true
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Device:
    get:
      tags: [Device]
      summary: Get implantable device
      description: Retrieves all Implantable Device (UDI) information for a patient. Confirmed endpoint (US Core Implantable Device Profile).
      operationId: getDevice
      parameters:
      - name: patient
        in: query
        required: true
        description: All UDI information for a specific patient.
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Observation:
    get:
      tags: [Observation]
      summary: Get observation
      description: >-
        Retrieves observations for a patient - vitals (blood pressure, body
        height/weight/temperature, heart rate, respiratory rate, pulse
        oximetry, inhaled oxygen concentration, pediatric BMI/weight-for-length/
        head-circumference percentiles) and smoking status. Confirmed endpoint
        (multiple US Core Observation profiles).
      operationId: getObservation
      parameters:
      - name: patient
        in: query
        required: true
        description: All observations for a specific patient.
        schema: { type: string }
      - name: code
        in: query
        required: false
        description: 'All observations with a specific code (e.g. 85354-9 for blood pressure).'
        schema: { type: string }
      - name: category
        in: query
        required: false
        description: 'All observations within a category (e.g. vital-signs).'
        schema: { type: string }
      - name: date
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Location:
    get:
      tags: [Location]
      summary: Get location
      description: Retrieves a location associated with a patient.
      operationId: getLocation
      parameters:
      - name: name
        in: query
        required: true
        description: All location resources that match a name.
        schema: { type: string }
      - name: address
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Medication:
    get:
      tags: [Medication]
      summary: Get medication
      description: Retrieves medication, in conjunction with a MedicationRequest query. Confirmed endpoint (US Core Medication Profile).
      operationId: getMedication
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /MedicationRequest:
    get:
      tags: [MedicationRequest]
      summary: Get medication request
      description: Retrieves medication history for a patient. Confirmed endpoint (US Core MedicationRequest Profile).
      operationId: getMedicationRequest
      parameters:
      - name: patient
        in: query
        required: true
        schema: { type: string }
      - name: intent
        in: query
        required: true
        description: 'All medications with a specific intent code (e.g. order).'
        schema: { type: string }
      - name: status
        in: query
        required: false
        description: 'All medications with a specific intent code and status code (e.g. active).'
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Organization:
    get:
      tags: [Organization]
      summary: Get organization
      description: Retrieves the organization associated with a patient or provider.
      operationId: getOrganization
      parameters:
      - name: name
        in: query
        required: true
        description: All organization resources matched to an organization's name.
        schema: { type: string }
      - name: address
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Practitioner:
    get:
      tags: [Practitioner]
      summary: Get practitioner
      description: Retrieves basic demographics about a practitioner.
      operationId: getPractitioner
      parameters:
      - name: name
        in: query
        required: true
        description: All demographics for a practitioner identified by name.
        schema: { type: string }
      - name: identifier
        in: query
        required: false
        description: 'All demographics for a practitioner identified by an identifier (e.g. NPI).'
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /PractitionerRole:
    get:
      tags: [PractitionerRole]
      summary: Get practitioner role
      description: Retrieves the role of a practitioner.
      operationId: getPractitionerRole
      parameters:
      - name: specialty
        in: query
        required: false
        description: Practitioner identified by specialty.
        schema: { type: string }
      - name: practitioner
        in: query
        required: false
        description: Practitioner identified by any part of a name.
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Procedure:
    get:
      tags: [Procedure]
      summary: Get procedure
      description: Retrieves procedures associated with a patient. Confirmed endpoint (US Core Procedure Profile).
      operationId: getProcedure
      parameters:
      - name: patient
        in: query
        required: true
        schema: { type: string }
      - name: date
        in: query
        required: false
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /Provenance:
    get:
      tags: [Provenance]
      summary: Get provenance
      description: Retrieves author and date information for elements of a patient's electronic health information (EHI). Confirmed endpoint (US Core Provenance Profile).
      operationId: getProvenance
      parameters:
      - name: patient
        in: query
        required: true
        description: 'Retrieves resources for a specific patient (patient + _revinclude=Provenance).'
        schema: { type: string }
      - name: id
        in: query
        required: false
        description: 'Retrieves resources for a specific US Core Profile resource type (id + _revinclude=Provenance).'
        schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/FHIRBundleResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
components:
  schemas:
    FHIRResource:
      type: object
      description: A standard HL7 FHIR R4 resource (US Core profiled). Structure follows the named US Core profile; not independently modeled here.
      properties:
        resourceType:
          type: string
        id:
          type: string
      additionalProperties: true
    FHIRBundle:
      type: object
      description: Standard FHIR R4 searchset Bundle wrapping zero or more FHIRResource entries.
      properties:
        resourceType:
          type: string
          example: Bundle
        type:
          type: string
          example: searchset
        total:
          type: integer
        entry:
          type: array
          items:
            type: object
            properties:
              resource:
                $ref: '#/components/schemas/FHIRResource'
    OperationOutcome:
      type: object
      description: Standard FHIR OperationOutcome error body.
      properties:
        resourceType:
          type: string
          example: OperationOutcome
        issue:
          type: array
          items:
            type: object
            properties:
              severity: { type: string }
              code: { type: string }
              diagnostics: { type: string }
  responses:
    FHIRBundleResponse:
      description: FHIR searchset Bundle.
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/FHIRBundle'
    BadRequest:
      description: 'Bad Request - the server cannot process the request due to an apparent client error.'
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Unauthorized:
      description: 'Unauthorized - the required authentication failed or was not provided.'
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Forbidden:
      description: 'Forbidden - a valid request was received but refused; typically the caller lacks the necessary permissions for the specified resource.'
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    TooManyRequests:
      description: 'Too Many Requests - too many requests sent in a given time period.'
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
  securitySchemes:
    smartOnFhirAuthCode:
      type: oauth2
      description: >-
        SMART on FHIR 3-legged OAuth 2.0 authorization-code flow for
        user-facing (patient/provider) applications. Authorization/token
        URLs are confirmed verbatim from the Tebra FHIR API User Guide. The
        scope list below is DERIVED, not verbatim - Tebra's guide instructs
        developers to "enter the SMART scopes required" without publishing an
        enumerated list, so these are the standard SMART v1 `patient/<Resource>.read`
        scope strings applied to the resource set Tebra's own guide documents.
      flows:
        authorizationCode:
          authorizationUrl: https://fhir.prd.cloud.tebra.com/smartauth/oauth/authorize
          tokenUrl: https://fhir.prd.cloud.tebra.com/smartauth/oauth/token
          scopes:
            patient/Patient.read: Read the patient's demographic record.
            patient/AllergyIntolerance.read: Read the patient's allergies/intolerances.
            patient/CarePlan.read: Read the patient's care plans.
            patient/CareTeam.read: Read the patient's care team.
            patient/Condition.read: Read the patient's conditions/problems.
            patient/DiagnosticReport.read: Read the patient's diagnostic reports.
            patient/DocumentReference.read: Read the patient's documents/clinical notes.
            patient/Encounter.read: Read the patient's encounters.
            patient/Goal.read: Read the patient's goals.
            patient/Immunization.read: Read the patient's immunizations.
            patient/Device.read: Read the patient's implantable devices.
            patient/Observation.read: Read the patient's observations (vitals/labs/smoking status).
            patient/Location.read: Read location resources.
            patient/Medication.read: Read medication resources.
            patient/MedicationRequest.read: Read the patient's medication requests.
            patient/Organization.read: Read organization resources.
            patient/Practitioner.read: Read practitioner resources.
            patient/PractitionerRole.read: Read practitioner-role resources.
            patient/Procedure.read: Read the patient's procedures.
            patient/Provenance.read: Read provenance resources.
            launch/patient: Identify the launch patient context.
            openid: OpenID Connect identity claim.
            fhirUser: FHIR user identity claim.
            offline_access: Obtain a refresh token.
    smartOnFhirClientCredentials:
      type: oauth2
      description: >-
        SMART on FHIR 2-legged OAuth 2.0 client-credentials flow for backend
        services applications (no end-user present). Token endpoint is
        confirmed verbatim from the Tebra FHIR API User Guide; Tebra currently
        supports only the Client Credentials workflow (not JWKS-based backend
        auth). Scope strings below are DERIVED (`system/<Resource>.read`,
        standard SMART v1 syntax), not verbatim - see note above.
      flows:
        clientCredentials:
          tokenUrl: https://fhir.prd.cloud.tebra.com/smartauth/oauth/token
          scopes:
            system/Patient.read: Read patient demographic records.
            system/Observation.read: Read observation resources.
            system/DocumentReference.read: Read document reference resources.