Tebra Patient API

openapi: 3.2.0
info:
  title: Tebra Patient API
  version: '1.0'
  contact:
    name: Tebra
    url: https://www.tebra.com/macra
  description: 'Operations tagged Patient across 2 of this provider''s published API definitions: tebra-fhir-api-openapi.yml, tebra-patient-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fhir.prd.cloud.tebra.com/fhir-request
  description: Tebra FHIR API (production, confirmed live)
- url: https://api.tebra.com/clinical/v1/api
  description: Tebra Clinical Data API (production)
tags:
- name: Patient
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'
      security:
      - smartOnFhirAuthCode: []
      - smartOnFhirClientCredentials: []
    servers:
    - url: https://fhir.prd.cloud.tebra.com/fhir-request
      description: Tebra FHIR API (production, confirmed live)
  /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_2'
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.tebra.com/clinical/v1/api
      description: Tebra Clinical Data API (production)
components:
  responses:
    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'
    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'
    FHIRBundleResponse:
      description: FHIR searchset Bundle.
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/FHIRBundle'
    TooManyRequests:
      description: Too Many Requests - too many requests sent in a given time period.
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Unauthorized_2:
      description: The API Key is missing, revoked, or otherwise not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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
    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
    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'
    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
    Error:
      type: object
      properties:
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Unauthorized
  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.
    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.
x-refined-from:
- tebra-fhir-api-openapi.yml
- tebra-patient-api-openapi.yml