openapi: 3.1.0
info:
  title: Penn Medicine FHIR R4 API
  description: |
    The University of Pennsylvania Health Systems FHIR Server is an Epic-backed HL7 FHIR R4
    implementation exposing CMS-mandated Patient Access and Provider Directory data, plus broader
    SMART on FHIR clinical resources. It conforms to US Core 6.1.0 and the HL7 FHIR Bulk Data Access
    (Flat FHIR) capability statement.

    Software: Epic (November 2025 release, released 2026-03-19).

    Authorization is OAuth 2.0 / SMART-on-FHIR (authorization code, refresh token, client credentials,
    JWT bearer). App registration is performed through Epic on FHIR (https://fhir.epic.com) by
    selecting Penn Medicine (Organization ID 346) as the target endpoint.
  version: '4.0.1'
  contact:
    name: Penn Medicine FHIR API
    url: https://www.pennmedicine.org/for-health-care-professionals/for-physicians/electronic-medical-records
  license:
    name: Epic FHIR Terms of Use
    url: https://fhir.epic.com
servers:
  - url: https://ssproxy.pennhealth.com/PRD-FHIR/api/FHIR/R4
    description: Penn Medicine FHIR R4 production endpoint (UPHS SecureSign Proxy)
tags:
  - name: Patient Access
    description: Patient-mediated clinical and claims data resources required under CMS-9115-F.
  - name: Provider Directory
    description: Public provider, organization, location, and endpoint resources required under CMS-9115-F.
  - name: Bulk Data
    description: HL7 FHIR Bulk Data Access (Flat FHIR) Group-level export.
  - name: SMART
    description: SMART on FHIR launch and discovery endpoints.
paths:
  /metadata:
    get:
      tags:
        - SMART
      summary: Read Capability Statement
      description: Returns the FHIR CapabilityStatement describing supported resources, interactions, and security.
      operationId: getCapabilityStatement
      responses:
        '200':
          description: CapabilityStatement
          content:
            application/fhir+json: {}
  /.well-known/smart-configuration:
    get:
      tags:
        - SMART
      summary: Read SMART Configuration
      description: SMART on FHIR discovery document advertising OAuth endpoints, scopes, and capabilities.
      operationId: getSmartConfiguration
      responses:
        '200':
          description: SMART configuration document
          content:
            application/json: {}
  /Patient/{id}:
    get:
      tags:
        - Patient Access
      summary: Read Patient
      operationId: readPatient
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Patient resource
          content:
            application/fhir+json: {}
  /Patient:
    get:
      tags:
        - Patient Access
      summary: Search Patient
      operationId: searchPatient
      parameters:
        - $ref: '#/components/parameters/_id'
        - $ref: '#/components/parameters/_count'
      responses:
        '200':
          description: Bundle of Patient resources
          content:
            application/fhir+json: {}
  /AllergyIntolerance:
    get:
      tags:
        - Patient Access
      summary: Search Allergy Intolerance
      operationId: searchAllergyIntolerance
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of AllergyIntolerance resources
          content:
            application/fhir+json: {}
  /Condition:
    get:
      tags:
        - Patient Access
      summary: Search Condition
      operationId: searchCondition
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/category'
      responses:
        '200':
          description: Bundle of Condition resources
          content:
            application/fhir+json: {}
  /Observation:
    get:
      tags:
        - Patient Access
      summary: Search Observation
      operationId: searchObservation
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/code'
      responses:
        '200':
          description: Bundle of Observation resources
          content:
            application/fhir+json: {}
  /MedicationRequest:
    get:
      tags:
        - Patient Access
      summary: Search Medication Request
      operationId: searchMedicationRequest
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of MedicationRequest resources
          content:
            application/fhir+json: {}
  /Immunization:
    get:
      tags:
        - Patient Access
      summary: Search Immunization
      operationId: searchImmunization
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of Immunization resources
          content:
            application/fhir+json: {}
  /Procedure:
    get:
      tags:
        - Patient Access
      summary: Search Procedure
      operationId: searchProcedure
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of Procedure resources
          content:
            application/fhir+json: {}
  /Encounter:
    get:
      tags:
        - Patient Access
      summary: Search Encounter
      operationId: searchEncounter
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of Encounter resources
          content:
            application/fhir+json: {}
  /DiagnosticReport:
    get:
      tags:
        - Patient Access
      summary: Search Diagnostic Report
      operationId: searchDiagnosticReport
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/category'
      responses:
        '200':
          description: Bundle of DiagnosticReport resources
          content:
            application/fhir+json: {}
  /DocumentReference:
    get:
      tags:
        - Patient Access
      summary: Search Document Reference
      operationId: searchDocumentReference
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of DocumentReference resources
          content:
            application/fhir+json: {}
  /Coverage:
    get:
      tags:
        - Patient Access
      summary: Search Coverage
      operationId: searchCoverage
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of Coverage resources
          content:
            application/fhir+json: {}
  /ExplanationOfBenefit:
    get:
      tags:
        - Patient Access
      summary: Search Explanation of Benefit
      operationId: searchExplanationOfBenefit
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of ExplanationOfBenefit resources
          content:
            application/fhir+json: {}
  /Claim:
    get:
      tags:
        - Patient Access
      summary: Search Claim
      operationId: searchClaim
      parameters:
        - $ref: '#/components/parameters/patient'
      responses:
        '200':
          description: Bundle of Claim resources
          content:
            application/fhir+json: {}
  /Practitioner:
    get:
      tags:
        - Provider Directory
      summary: Search Practitioner
      operationId: searchPractitioner
      parameters:
        - $ref: '#/components/parameters/_id'
        - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Bundle of Practitioner resources
          content:
            application/fhir+json: {}
  /PractitionerRole:
    get:
      tags:
        - Provider Directory
      summary: Search Practitioner Role
      operationId: searchPractitionerRole
      parameters:
        - $ref: '#/components/parameters/_id'
        - $ref: '#/components/parameters/specialty'
      responses:
        '200':
          description: Bundle of PractitionerRole resources
          content:
            application/fhir+json: {}
  /Organization:
    get:
      tags:
        - Provider Directory
      summary: Search Organization
      operationId: searchOrganization
      parameters:
        - $ref: '#/components/parameters/_id'
        - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Bundle of Organization resources
          content:
            application/fhir+json: {}
  /Location:
    get:
      tags:
        - Provider Directory
      summary: Search Location
      operationId: searchLocation
      parameters:
        - $ref: '#/components/parameters/_id'
        - $ref: '#/components/parameters/address'
      responses:
        '200':
          description: Bundle of Location resources
          content:
            application/fhir+json: {}
  /Endpoint:
    get:
      tags:
        - Provider Directory
      summary: Search Endpoint
      operationId: searchEndpoint
      parameters:
        - $ref: '#/components/parameters/_id'
      responses:
        '200':
          description: Bundle of Endpoint resources
          content:
            application/fhir+json: {}
  /Group/{id}/$export:
    get:
      tags:
        - Bulk Data
      summary: Export Group Bulk Data
      description: |
        Initiates a Bulk Data (Flat FHIR) export for a Group of patients per
        HL7 FHIR Bulk Data Access IG. Requires client_credentials authentication and the
        `system/*.read` scope. Status is polled at the Content-Location URL.
      operationId: exportGroup
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: _type
          in: query
          schema:
            type: string
      responses:
        '202':
          description: Export accepted; poll Content-Location header for status.
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
    _id:
      name: _id
      in: query
      schema:
        type: string
    _count:
      name: _count
      in: query
      schema:
        type: integer
    patient:
      name: patient
      in: query
      required: true
      schema:
        type: string
    category:
      name: category
      in: query
      schema:
        type: string
    code:
      name: code
      in: query
      schema:
        type: string
    name:
      name: name
      in: query
      schema:
        type: string
    specialty:
      name: specialty
      in: query
      schema:
        type: string
    address:
      name: address
      in: query
      schema:
        type: string
  securitySchemes:
    smartOnFhir:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://ssproxy.pennhealth.com/PRD-FHIR/oauth2/authorize
          tokenUrl: https://ssproxy.pennhealth.com/PRD-FHIR/oauth2/token
          scopes:
            launch: SMART app launch context
            openid: OpenID Connect
            fhirUser: Current FHIR user identity
            profile: User profile claims
            offline_access: Refresh token issuance
        clientCredentials:
          tokenUrl: https://ssproxy.pennhealth.com/PRD-FHIR/oauth2/token
          scopes:
            system/*.read: System-level read of all resources (Bulk Data)
security:
  - smartOnFhir: []