openapi: 3.1.0
info:
  title: WellCare FHIR Patient Access API
  description: >-
    The WellCare FHIR Patient Access API enables members and authorized
    third-party applications to securely access and exchange health data
    including medical, pharmacy, dental, and vision claims and clinical
    information. The API supports HL7 FHIR R4 standards and SMART on FHIR
    authorization, providing access to up to 5 years of historical health
    information. Required under CMS Interoperability and Patient Access final
    rule (CMS-9115-F) for Medicaid and Medicare Advantage plans. Access is
    managed through the Centene Partner Portal at partners.centene.com/apis.
  version: '1.0'
  contact:
    url: https://www.wellcare.com/en/interoperability-and-patient-access
servers:
  - url: https://partners.centene.com
tags:
  - name: Patient
    description: Patient demographic and identity resources.
  - name: Coverage
    description: Member insurance coverage and enrollment information.
  - name: Explanation of Benefits
    description: Claims and EOB data for medical, pharmacy, dental, and vision.
  - name: Condition
    description: Member diagnosed conditions and clinical data.
  - name: Observation
    description: Clinical observations, lab results, and vital signs.
  - name: Medication Request
    description: Prescribed medications and medication orders.
  - name: Immunization
    description: Immunization records and history.
  - name: Procedure
    description: Procedures performed on the member.
  - name: Encounter
    description: Member care encounters and visits.
paths:
  /fhir/r4/Patient/{id}:
    get:
      operationId: getPatient
      summary: Get Patient
      description: >-
        Retrieves a patient resource by FHIR Patient ID for an authenticated
        member, returning demographic information including name, birthdate,
        address, and contact details.
      tags:
        - Patient
      parameters:
        - name: id
          in: path
          description: The FHIR Patient resource ID.
          required: true
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/Patient.read
      responses:
        '200':
          description: Patient resource returned successfully.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          description: Unauthorized - invalid or missing access token.
        '404':
          description: Patient not found.
  /fhir/r4/Coverage:
    get:
      operationId: listCoverage
      summary: List Coverage
      description: >-
        Retrieves insurance coverage resources for a member, including
        plan details, enrollment period, group information, and benefit
        categories for medical, pharmacy, dental, and vision coverage.
      tags:
        - Coverage
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID to retrieve coverage for.
          required: true
          schema:
            type: string
        - name: _count
          in: query
          description: Number of results per page.
          schema:
            type: integer
        - name: _page
          in: query
          description: Page number for paginated results.
          schema:
            type: integer
      security:
        - smartOnFhir:
            - patient/Coverage.read
      responses:
        '200':
          description: Bundle of Coverage resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/ExplanationOfBenefit:
    get:
      operationId: listExplanationOfBenefit
      summary: List Explanation of Benefit
      description: >-
        Retrieves Explanation of Benefit (EOB) resources representing adjudicated
        medical, pharmacy, dental, and vision claims for a member. Supports up
        to 5 years of historical claims data as required by CMS interoperability
        rules.
      tags:
        - Explanation of Benefits
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID to retrieve EOBs for.
          required: true
          schema:
            type: string
        - name: service-date
          in: query
          description: Filter by service date range (format YYYY-MM-DD or YYYY-MM-DD,YYYY-MM-DD).
          schema:
            type: string
        - name: type
          in: query
          description: Filter by claim type (e.g., pharmacy, oral, vision, institutional, professional).
          schema:
            type: string
        - name: _count
          in: query
          description: Number of results per page.
          schema:
            type: integer
      security:
        - smartOnFhir:
            - patient/ExplanationOfBenefit.read
      responses:
        '200':
          description: Bundle of ExplanationOfBenefit resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/Condition:
    get:
      operationId: listConditions
      summary: List Conditions
      description: >-
        Retrieves Condition resources representing a member's diagnosed conditions,
        including ICD-10 codes, clinical status, and onset dates from clinical data.
      tags:
        - Condition
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID.
          required: true
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/Condition.read
      responses:
        '200':
          description: Bundle of Condition resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/Observation:
    get:
      operationId: listObservations
      summary: List Observations
      description: >-
        Retrieves Observation resources including laboratory results, vital
        signs, and other clinical measurements for an authenticated member.
      tags:
        - Observation
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID.
          required: true
          schema:
            type: string
        - name: category
          in: query
          description: Filter by observation category (e.g., laboratory, vital-signs).
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/Observation.read
      responses:
        '200':
          description: Bundle of Observation resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/MedicationRequest:
    get:
      operationId: listMedicationRequests
      summary: List Medication Requests
      description: >-
        Retrieves MedicationRequest resources representing prescribed medications
        and medication orders for an authenticated member.
      tags:
        - Medication Request
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID.
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Filter by medication request status (active, completed, stopped).
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/MedicationRequest.read
      responses:
        '200':
          description: Bundle of MedicationRequest resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/Immunization:
    get:
      operationId: listImmunizations
      summary: List Immunizations
      description: >-
        Retrieves Immunization resources representing a member's immunization
        history including vaccine type, administration date, and lot number.
      tags:
        - Immunization
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID.
          required: true
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/Immunization.read
      responses:
        '200':
          description: Bundle of Immunization resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
  /fhir/r4/Encounter:
    get:
      operationId: listEncounters
      summary: List Encounters
      description: >-
        Retrieves Encounter resources representing care encounters, visits, and
        admissions for an authenticated member, including encounter type, date,
        provider, and location.
      tags:
        - Encounter
      parameters:
        - name: patient
          in: query
          description: The FHIR Patient ID.
          required: true
          schema:
            type: string
        - name: date
          in: query
          description: Filter by encounter date range.
          schema:
            type: string
      security:
        - smartOnFhir:
            - patient/Encounter.read
      responses:
        '200':
          description: Bundle of Encounter resources returned.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          description: Unauthorized.
components:
  securitySchemes:
    smartOnFhir:
      type: oauth2
      description: SMART on FHIR OAuth 2.0 authorization for patient-facing apps.
      flows:
        authorizationCode:
          authorizationUrl: https://partners.centene.com/oauth2/authorize
          tokenUrl: https://partners.centene.com/oauth2/token
          scopes:
            patient/Patient.read: Read patient demographic data
            patient/Coverage.read: Read coverage and enrollment data
            patient/ExplanationOfBenefit.read: Read claims and EOB data
            patient/Condition.read: Read diagnosed conditions
            patient/Observation.read: Read observations and lab results
            patient/MedicationRequest.read: Read medication requests
            patient/Immunization.read: Read immunization records
            patient/Encounter.read: Read care encounters
  schemas:
    Bundle:
      type: object
      description: A FHIR Bundle resource containing a collection of resources.
      properties:
        resourceType:
          type: string
          example: Bundle
        id:
          type: string
        type:
          type: string
          enum: [searchset, collection, transaction, history]
        total:
          type: integer
        link:
          type: array
          items:
            type: object
            properties:
              relation:
                type: string
              url:
                type: string
        entry:
          type: array
          items:
            type: object
            properties:
              fullUrl:
                type: string
              resource:
                type: object
    Patient:
      type: object
      description: A FHIR Patient resource.
      properties:
        resourceType:
          type: string
          example: Patient
        id:
          type: string
        name:
          type: array
          items:
            type: object
            properties:
              family:
                type: string
              given:
                type: array
                items:
                  type: string
        birthDate:
          type: string
          format: date
        gender:
          type: string
          enum: [male, female, other, unknown]
        address:
          type: array
          items:
            type: object