ExplanationOfBenefit

Explanation of Benefit (EOB) is a FHIR resource that contains a statement from a health insurance plan describing what costs will be covered for care and services received by a covered person.

Because EOBs document what the insurance plan is covering and paying for, they contain detailed information about the medical services, procedures, medications, diagnoses, and healthcare providers involved in the care. This clinical and administrative detail is essential for the insurance company to justify and track their payments.

Traditionally, health insurance plans send claims data to their vendors and business associates under several use cases (care coordination, utilization management, predictive analytics) using a variety of custom, one-off, flat file extracts.

Flexpa, instead, makes this data available as EOB FHIR resources in the format described by the CARIN for Blue Button® Framework and Common Payer Consumer Data Set (CPCDS).

EOBs are structured around three primary claim types, each with distinct data requirements, value sets, and business rules:

Institutional - Inpatient and outpatient facility care, procedures, and services
Professional & Non-Clinician - Physician and professional care
Pharmacy - Prescription medications and pharmacy products

This reference explains the common elements all EOBs share and the unique elements for each claim type.

FHIR API

https://api.flexpa.com/fhir/ExplanationOfBenefit

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

Looking for CARIN Blue Button details?

Claims Guide

Comprehensive guide to understanding and working with claims data

Read the Claims Guide →Soon

#Schema

#All Claims

The FHIR ExplanationOfBenefit (EOB) resource represents a health plan's statement of what costs were covered for care and services. As a FHIR resource, it follows standard FHIR patterns with common elements like resourceType, id, meta, and identifier, while also including specialized elements for claims data.

All EOBs, regardless of claim type, share a set of common elements that provide essential information about the claim processing and adjudication.

In the type-specific examples that follow, we focus on the unique FHIR elements for each claim type, but you can expect these common building blocks elements to be present in all EOBs.

Elements

identifierIdentifier: Business identifiers for the claim
typeCodeableConcept: Unique claim identifier from the payer; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType
Identifier types for CARIN Blue Button
Codes
uc
Indicates that the claim identifier is that assigned by a payer for a claim received from a provider or subscriber
statuscode: The status of the EOB as a resource - see also outcome for the status of the claim processing and payment.type for the adjudication status; Codes
active
The explanation of benefit is active and ready for use
cancelled
The explanation of benefit has been cancelled
draft
The explanation of benefit is in draft status
entered-in-error
The explanation of benefit was entered in error
typeCodeableConcept: The type of claim represented by the EOB; Systemhttp://terminology.hl7.org/CodeSystem/claim-type
FHIR claim type codes
Codes
institutional
Hospital, clinic and both inpatient and outpatient claims
pharmacy
Pharmacy claims for goods and services
professional
Claims from a doctors office and other professional services
usecode: The nature of the claim request - note that claim is the expected value for CMS-9115 claims; Codes
claim
Active and ready for use
preauthorization
Active and ready for use
predetermination
Active and ready for use
patientReference(Patient): Reference to the patient who was the subject of the care and services
providerReference(Practitioner|Organization): Reference to the provider who delivered the service
billablePeriodPeriod: The period for which services are being billed
totalarray: Financial summary by category (submitted, allowed, paid, etc.). See our Financial Data Guide for more details.
outcomecode: The outcome of the claim processing.; Codes
queued
The claim has been received and is queued for processing
complete
The claim processing has been completed
error
An error occurred during claim processing
partial
The claim has been partially processed
payeeBackboneElement: Recipient of benefits payable - not necessarily the same as the patient (i.e. in the case of a child covered by a parent's insurance)
typeCodeableConcept: Category of recipient; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayeeType
Payee type
Codes
beneficiary
The beneficiary (covered person) who will be reimbursed.; Systemhttp://terminology.hl7.org/CodeSystem/payeetype
Standard FHIR payee type codes
Codes
subscriber
The subscriber (policy holder) will be reimbursed.
provider
Any benefit payable will be paid to the provider (Assignment of Benefit).
other
Any benefit payable will be paid to a third party such as a guarantor.
partyReference(Organization|Patient|Practitioner): Recipient reference
insuranceBackboneElement: Patient insurance information
focalboolean: Coverage to be used for adjudication
coverageReference(Coverage): Insurance information
paymentBackboneElement: Payment Details
typeCodeableConcept: Partial or complete payment; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus
C4BB Payer Claim Payment Status Code
Codes
paid
Indicates if the claim was approved for payment
denied
Indicates if the claim was denied
partiallypaid
Indicates that some line items on the claim were denied
datedate: Expected date of payment

All Claims EOB Example

{
  "resourceType": "ExplanationOfBenefit",
  "id": "f6916af5-d5ec-4aee-8d36-b82cbef14eb0",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "uc"
          }
        ]
      },
      "value": "123456"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "institutional"
      }
    ]
  },
  "use": "claim",
  "patient": { "reference": "Patient/example" },
  "provider": { "reference": "Practitioner/example" },
  "billablePeriod": {
    "start": "2023-01-01",
    "end": "2023-01-31"
  },
  "total": [
    {
      "category": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBAdjudication",
            "code": "submitted"
          }
        ]
      },
      "amount": { "value": 1000, "currency": "USD" }
    }
  ],
  "outcome": "complete",
  "payee": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayeeType",
          "code": "beneficiary"
        }
      ]
    },
    "party": { "reference": "Patient/example" }
  },
  "insurance": {
    "focal": true,
    "coverage": { "reference": "Coverage/example" }
  },
  "payment": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus",
          "code": "paid"
        }
      ]
    },
  }
}

#Institutional Claims

Institutional claims represent services provided in healthcare facilities such as hospitals, clinics, skilled nursing facilities, and outpatient centers including procedures, the use of equipment and supplies, and other charges.

Institutional claims are a key source for CPT and HCPCS codes for procedures and services, ICD-10-CM and ICD-9 codes for diagnoses, and ICD-10-PCS codes for inpatient procedures.

There are two significant institutional claim subtypes:

Inpatient Institutional - Hospital admissions and inpatient stays. Typically defined by being "admitted" to the facility, for example when requiring an overnight stay.
Outpatient Institutional - Outpatient facility services and procedures where no admission occurred.

Institutional claims are equivalent to, and represented in other contexts, as:

CMS-1450 - The official CMS form for institutional claims
UB-04 - Uniform Billing Form used by hospitals and other institutional providers
EDI 837I - Electronic Data Interchange format for institutional healthcare claims

Elements

itemarray: Product or service provided
revenueCoding: Revenue codes are represented as "FL 42 - Revenue Codes" in CMS-1450 / UB-04. They categorize the type of accommodation, ancillary service, or billing unit used by the provider.; Systemhttps://www.nubc.org/CodeSystem/RevenueCodes
These codes are listed within the UB-04 Data Specifications Manual
Example Codes
0110
Room and board - Private (one bed)
productOrServiceCoding: Procedure codes from the CPT and HCPCS files and the rate codes from the HIPPS files; Systemhttp://www.ama-assn.org/go/cpt
Current Procedural Terminology codes as maintained by the AMA
Example Codes
10021
Fine needle aspiration; Systemhttps://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
Level II HCPCS codes represent items, supplies, and services not covered by CPT codes
Example Codes
A0425
Ground mileage, per statute mile
modifierCoding: Modifiers help further describe a procedure code without changing its definition; Systemhttp://www.ama-assn.org/go/cpt
Current Procedural Terminology modifier codes as maintained by the AMA
Example Codes
50
Bilateral procedure; Systemhttps://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
Level II HCPCS modifier codes represent items, supplies, and services not covered by CPT codes
Example Codes
LT
Left side
diagnosisBackboneElement: Diagnosis information for the claim
typeCoding: Type of diagnosis (principal, other, etc.); Systemhttp://terminology.hl7.org/CodeSystem/ex-diagnosistype
Standard FHIR diagnosis types
Codes
principal
The single medical diagnosis that is most relevant to the patient's chief complaint or need for treatment
admitting
The diagnosis given as the reason why the patient was admitted to the hospital. Only used for inpatient institutional claims.; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimDiagnosisType
CARIN Blue Button diagnosis types.
Codes
other
Required when other conditions coexist or develop subsequently during the treatment
externalcauseofinjury
Required when an external cause of injury is needed to describe the injury
patientreasonforvisit
Identifies the patient's reason for the outpatient institutional visit. Only used for outpatient institutional claims.
diagnosisCodeableConceptCodeableConcept: Diagnosis codes (ICD-10-CM or ICD-9); Systemhttp://hl7.org/fhir/sid/icd-10-cm
International Classification of Diseases, 10th Revision, Clinical Modification (ICD-10-CM) codes used for diagnosis coding in the United States.
Example Codes
Z00.00
Encounter for general adult medical examination without abnormal findings; Systemhttp://terminology.hl7.org/CodeSystem/icd9
International Classification of Diseases, 9th Revision, Clinical Modification (ICD-9-CM) codes for diagnosis coding.
Example Codes
V70.0
Routine medical examination
onAdmissionCodeableConcept: Present on admission indicator. Only used for inpatient institutional claims.; Systemhttps://www.nubc.org/CodeSystem/PresentOnAdmissionIndicator
NUBC Present On Admission Indicator Codes used to report whether or not a condition was present on admission. These codes act as modifiers to further define diagnosis codes (ICD-9 or ICD-10). Used in UB-04 FL 67 - Present On Admission Indicator.
Example Codes
Y
Present at the time of inpatient admission
procedureBackboneElement: Clinical procedures performed. Only used for inpatient institutional claims.
sequencepositiveInt: Procedure instance identifier
typeCodeableConcept: Category of procedure; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimProcedureType
C4BB Claim Procedure Type codes
Codes
principal
The Principal Procedure is based on the relation of the procedure to the Principal Diagnosis
other
Other procedures performed during the inpatient institutional admission
datedatetime: When the procedure was performed
procedureCodeableConceptCodeableConcept: Specific clinical procedure; Systemhttp://www.cms.gov/Medicare/Coding/ICD10
ICD-10 Procedure Coding System (ICD-10-PCS) - the replacement for ICD-9-CM volume 3, effective October 1, 2015. Published by CMS for classifying procedures performed in hospital inpatient health care settings.
Example Codes
0DT70ZZ
Resection of duodenum, open approach; Systemhttp://www.cms.gov/Medicare/Coding/ICD9
International Classification of Diseases, Ninth Revision, Clinical Modification (ICD-9-CM) volume 3 procedure codes - the official system for assigning codes to procedures associated with hospital utilization in the United States (prior to October 1, 2015).
Example Codes
45.13
Other endoscopy of small bowel
supportingInfoBackboneElement: Supporting information for the claim
categoryCodeableConcept: Category of supporting information; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBSupportingInfoType
C4BB Supporting Info Type codes
Codes
pointoforigin
UB-04 Source of Admission (FL-15) identifies the place where the patient was identified as needing admission to a facility.
typeofbill
UB-04 Type of Bill (FL-04) provides specific information for payer purposes.
admissionperiod
Dates corresponding with the admission and discharge of the beneficiary to a facility
clmrecvddate
Date the claim was received by the payer.
admtype
UB-04 Priority of the admission (FL-14) indicates, for example, an admission type of elective indicates that the patient's condition permitted time for medical services to be scheduled.
discharge-status
UB-04 Discharge Status (FL-17) indicates the patient's status as of the discharge date for a facility stay.
drg
DRG (Diagnosis Related Group), including the code system, the DRG version and the code value
medicalrecordnumber
Patient Medical Record Number associated with the specific claim.
patientaccountnumber
Patient Account Number associated with the specific claim.
codeCodeableConcept: Additional code when category is pointoforigin, typeofbill, admtype, discharge-status, or drg; Systemhttps://www.nubc.org/CodeSystem/PointOfOrigin
Used when category = pointoforigin
Example Codes
1
Non-health care facility point of origin; Systemhttps://www.nubc.org/CodeSystem/TypeOfBill
Used when category = typeofbill
Example Codes
111
Hospital Inpatient - Admit thru Discharge Claim; Systemhttps://www.nubc.org/CodeSystem/PriorityTypeOfAdmitOrVisit
Used when category = admtype
Example Codes
1
Emergency; Systemhttps://www.nubc.org/CodeSystem/PatDischargeStatus
Used when category = discharge-status
Example Codes
01
Discharged to home or self care (routine discharge); Systemhttps://www.cms.gov/Medicare/Medicare-Fee-for-Service-Payment/AcuteInpatientPPS/MS-DRG-Classifications-and-Software
Used when category = drg - MS-DRG classifications from CMS
Example Codes
470
Major joint replacement or reattachment of lower extremity w/o MCC; Systemhttp://uri.hddaccess.com/cs/apdrg
Used when category = drg - All Patient DRG (AP-DRG) classifications
Example Codes
209
Major joint and limb reattachment procedures; Systemhttp://uri.hddaccess.com/cs/aprdrg
Used when category = drg - All Patient Refined DRG (APR-DRG) classifications
Example Codes
302
Kidney and urinary tract procedures
timingPeriodPeriod: Period when category is admissionperiod
timingDatedate: Date when category is clmrecvddate
valueStringstring: String value when category is medicalrecordnumber or patientaccountnumber

Institutional EOB Example

{
  "resourceType": "ExplanationOfBenefit",
  "id": "f6916af5-d5ec-4aee-8d36-b82cbef14eb0",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "uc"
          }
        ]
      },
      "value": "123456"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "institutional"
      }
    ]
  },
  "use": "claim",
  "patient": { "reference": "Patient/example" },
  "provider": { "reference": "Practitioner/example" },
  "billablePeriod": {
    "start": "2023-01-01",
    "end": "2023-01-31"
  },
  "item": [
    {
      "sequence": 1,
      "revenue": {
        "coding": [
          {
            "system": "https://www.nubc.org/CodeSystem/RevenueCodes",
            "code": "0110",
            "definition": "Room and board - Private (one bed)"
          }
        ]
      },
      "productOrService": {
        "coding": [
          {
            "system": "https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
            "code": "27447",
            "definition": "Arthroplasty, knee, condyle and plateau"
          }
        ]
      },
      "modifier": {
        "coding": [
          {
            "system": "ttps://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
            "code": "LT",
            "definition": "Left side"
          }
        ]
      }
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "type": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/ex-diagnosistype",
              "code": "principal",
              "display": "Principal Diagnosis"
            }
          ]
        }
      ],
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "M17.12",
            "display": "Unilateral primary osteoarthritis, left knee"
          }
        ]
      }
    }
  ],
  "procedure": [
    {
      "sequence": 1,
      "type": [
        {
          "coding": [
            {
              "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimProcedureType",
              "code": "principal",
              "display": "Principal Procedure"
            }
          ]
        }
      ],
      "date": "2024-01-15",
      "procedureCodeableConcept": {
        "coding": [
          {
            "system": "http://www.cms.gov/Medicare/Coding/ICD10",
            "code": "0SRD0JZ",
            "display": "Replacement of Left Knee Joint with Synthetic Substitute"
          }
        ]
      }
    }
  ],
   "total": [
    {
      "category": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBAdjudication",
            "code": "submitted"
          }
        ]
      },
      "amount": { "value": 1000, "currency": "USD" }
    }
  ],
  "outcome": "complete",
  "payee": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayeeType",
          "code": "beneficiary"
        }
      ]
    },
    "party": { "reference": "Patient/example" }
  },
  "insurance": {
    "focal": true,
    "coverage": { "reference": "Coverage/example" }
  },
  "payment": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus",
          "code": "paid"
        }
      ]
    },
  }
}
}

#Professional Claims

Professional claims represent services provided by healthcare professionals in their professional capacity, including physicians, nurses, therapists, and other non-clinician providers. These claims cover office visits, consultations, procedures, and diagnostic services performed in various settings.

Professional claims follow the Professional & Non-Clinician profile, which encompasses services provided by:

Physicians - Primary care doctors, specialists, and other medical professionals
Non-Clinician Providers - Physical therapists, occupational therapists, speech therapists, and other healthcare professionals
Ancillary Services - Laboratory services, diagnostic imaging, and other professional services

Professional claims are equivalent to, and represented in other contexts, as:

CMS-1500 - The official CMS form for professional claims
EDI 837P - Electronic Data Interchange format for professional healthcare claims

Elements

itemarray: Product or service provided
productOrServiceCoding: Medical services, procedures, and supplies provided by healthcare professionals; Systemhttp://www.ama-assn.org/go/cpt
Current Procedural Terminology codes as maintained by the AMA
Example Codes
36415
Collection of venous blood by venipuncture; Systemhttps://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
Level II HCPCS codes represent items, supplies, and services not covered by CPT codes
Example Codes
A4550
Surgical trays
modifierCoding: Modifiers provide additional information about the service performed; Systemhttp://www.ama-assn.org/go/cpt
Current Procedural Terminology modifier codes
Example Codes
50
Bilateral procedure; Systemhttps://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
Level II HCPCS modifier codes
Example Codes
LT
Left side
locationCodeableConceptCodeableConcept: Place of service where the encounter took place; Systemhttps://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set
Place of Service codes maintained by CMS
Example Codes
11
Office
servicedDatedate: Date when the service was performed
servicedPeriodPeriod: Period over which the service was provided (alternative to servicedDate)
diagnosisBackboneElement: Diagnosis information for the claim
typeCoding: Type of diagnosis; Systemhttp://terminology.hl7.org/CodeSystem/ex-diagnosistype
Standard FHIR diagnosis types
Codes
principal
The single medical diagnosis that is most relevant to the patient's chief complaint or need for treatment; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimDiagnosisType
CARIN Blue Button diagnosis types
Codes
secdonary
Required when necessary to report additional diagnoses on professional and non-clinician claims
diagnosisCodeableConceptCodeableConcept: Diagnosis codes (ICD-10-CM or ICD-9); Systemhttp://hl7.org/fhir/sid/icd-10-cm
International Classification of Diseases, 10th Revision, Clinical Modification (ICD-10-CM) codes
Example Codes
M79.3
Panniculitis, unspecified; Systemhttp://terminology.hl7.org/CodeSystem/icd9
International Classification of Diseases, 9th Revision, Clinical Modification (ICD-9-CM) codes
Example Codes
V70.0
Routine medical examination
supportingInfoBackboneElement: Supporting information for the claim
categoryCodeableConcept: Category of supporting information; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBSupportingInfoType
C4BB Supporting Info Type codes
Codes
billingnetworkcontractingstatus
Indicates that the Billing Provider has a contract with the Payer as of the effective date of service or admission.
performingnetworkcontractingstatus
Indicates that the Performing Provider has a contract with the Payer as of the effective date of service or admission.
clmrecvddate
Date the claim was received by the payer.
servicefacility
Name, address, and provider identifier of the facility where services were performed.
medicalrecordnumber
Patient Medical Record Number associated with the specific claim.
patientaccountnumber
Patient Account Number associated with the specific claim.
codeCodeableConcept: Additional code when category is billingnetworkcontractingstatus or performingnetworkcontractingstatus; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus
Used when category = billingnetworkcontractingstatus
Example Codes
contracted
Indicates the provider was contracted for the service
non-contracted
Indicates the provider was not contracted for the service
timingDatedate: Date when category is clmrecvddate
valueStringstring: String value when category is medicalrecordnumber or patientaccountnumber
valueReferenceReference(Organization): Service Facility Location information conveys the name, full address and identifier of the facility where services were rendered when that is different from the Billing/Rendering Provider - when category is servicefacility

Professional EOB Example

{
  "resourceType": "ExplanationOfBenefit",
  "id": "f6916af5-d5ec-4aee-8d36-b82cbef14eb0",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "uc"
          }
        ]
      },
      "value": "123456"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "professional"
      }
    ]
  },
  "use": "claim",
  "patient": { "reference": "Patient/example" },
  "provider": { "reference": "Practitioner/example" },
  "billablePeriod": {
    "start": "2023-01-01",
    "end": "2023-01-31"
  },
  "item": [
    {
      "sequence": 1,
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "99213",
            "display": "Office or other outpatient visit"
          }
        ]
      },
      "servicedDate": "2024-01-20",
      "locationCodeableConcept": {
        "coding": [
          {
            "system": "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
            "code": "11",
            "display": "Office"
          }
        ]
      },
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "Z00.00",
            "display": "Encounter for general adult medical examination without abnormal findings"
          }
        ]
      },
      "type": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/ex-diagnosistype",
              "code": "principal",
              "display": "Principal Diagnosis"
            }
          ]
        }
      ]
    }
  ],
  "total": [
    {
      "category": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBAdjudication",
            "code": "submitted"
          }
        ]
      },
      "amount": { "value": 1000, "currency": "USD" }
    }
  ],
  "outcome": "complete",
  "payee": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayeeType",
          "code": "beneficiary"
        }
      ]
    },
    "party": { "reference": "Patient/example" }
  },
  "insurance": {
    "focal": true,
    "coverage": { "reference": "Coverage/example" }
  },
  "payment": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus",
          "code": "paid"
        }
      ]
    },
  }
}

#Pharmacy Claims

Pharmacy claims represent prescription medications and pharmaceutical services provided by pharmacies, including prescription drugs, compound medications, and over-the-counter items covered by the health plan.

Pharmacy claims are a key source for NDC (National Drug Code) identifiers for medications, RxNorm codes for standardized medication names, and pharmacy-specific transaction details like days supply, refill information, and prescriber instructions.

Pharmacy claims follow the Pharmacy profile, which encompasses:

Prescription Medications - Brand name and generic drugs dispensed by pharmacies
Compound Medications - Custom-prepared medications mixed by pharmacists
Over-the-Counter Items - Non-prescription items covered by the health plan
Pharmacy Services - Professional services provided by pharmacists

Pharmacy claims are equivalent to, and represented in other contexts, as:

NCPDP Standard - National Council for Prescription Drug Programs electronic transaction standards
EDI 837P - Electronic Data Interchange format for pharmacy claims (less common)

Elements

prescriptionReference(MedicationRequest): Reference to the original prescription (MedicationRequest resource)
itemarray: Medication dispensed
productOrServiceCoding: Medication codes using NDC (National Drug Code) or RxNorm identifiers; Systemhttp://hl7.org/fhir/sid/ndc
National Drug Code (NDC) - FDA's unique identifier for drug packages in the U.S.
Example Codes
0777-3105-02
Lisinopril 10mg tablets, 30 count bottle; Systemhttp://www.nlm.nih.gov/research/umls/rxnorm
RxNorm - standardized nomenclature for clinical drugs produced by the National Library of Medicine
Example Codes
314076
Lisinopril 10 MG Oral Tablet
servicedDatedate: Date when the medication was dispensed
quantityQuantity: Quantity of medication dispensed
careTeamBackboneElement: Providers involved in the prescription and dispensing
providerReference(Practitioner|Organization): Reference to the prescribing provider or dispensing pharmacy
roleCodeableConcept: Role of the care team member; Systemhttp://terminology.hl7.org/CodeSystem/claimcareteamrole
Standard FHIR care team roles
Codes
primary
Primary provider; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole
CARIN Blue Button care team roles
Codes
prescribing
Prescribing provider
supportingInfoBackboneElement: Supporting information for the pharmacy claim
categoryCodeableConcept: Category of supporting information; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBSupportingInfoType
C4BB Supporting Info Type codes
Codes
dayssupply
Days supply of medication dispensed
refillnum
Refill number for the dispensed medication
brandgenericindicator
Indicates whether the dispensed medication is brand name or generic
dawcode
Dispense as Written (DAW) code indicating prescriber's instructions regarding substitution
rxorigincode
Code indicating the source/origin of the prescription (electronic, written, etc.)
compoundcode
Indicates whether the dispensed medication is a compound drug
billingnetworkcontractingstatus
Indicates that the Billing Provider has a contract with the Payer
clmrecvddate
Date the claim was received by the payer
valueQuantityQuantity: Quantity value when category is dayssupply or refillnum
codeCodeableConcept: Additional code when category requires it; Systemhttp://terminology.hl7.org/CodeSystem/NCPDPBrandGenericIndicator
Used when category = brandgenericindicator
Example Codes
1
Generic; Systemhttp://terminology.hl7.org/CodeSystem/NCPDPDispensedAsWrittenOrProductSelectionCode
Used when category = dawcode
Example Codes
0
No product selection indicated; Systemhttp://terminology.hl7.org/CodeSystem/NCPDPPrescriptionOriginCode
Used when category = rxorigincode
Example Codes
0
Not specified; Systemhttp://terminology.hl7.org/CodeSystem/NCPDPCompoundCode
Used when category = compoundcode
Example Codes
0
Not a compound; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayerAdjudicationStatus
Used when category = billingnetworkcontractingstatus
Example Codes
contracted
Provider is contracted with the payer
non-contracted
Provider is not contracted with the payer
timingDatedate: Date when category is clmrecvddate

Pharmacy EOB Example

{
  "resourceType": "ExplanationOfBenefit",
  "id": "pharmacy-example-1",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-ExplanationOfBenefit-Pharmacy"
    ]
  },
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "uc"
          }
        ]
      },
      "system": "https://www.pharmacy.com/fhir/EOBIdentifier",
      "value": "RX789012345"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "pharmacy",
        "display": "Pharmacy"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/patient-123"
  },
  "billablePeriod": {
    "start": "2024-01-15",
    "end": "2024-01-15"
  },
  "created": "2024-01-15",
  "insurer": {
    "display": "Example Health Plan"
  },
  "provider": {
    "identifier": {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "1234567890"
    },
    "display": "Community Pharmacy"
  },
  "prescription": {
    "identifier": {
      "system": "http://hl7.org/fhir/sid/ndc",
      "value": "0777-3105-02"
    },
    "display": "Lisinopril 10mg tablets"
  },
  "outcome": "complete",
  "careTeam": [
    {
      "sequence": 1,
      "provider": {
        "identifier": {
          "system": "http://hl7.org/fhir/sid/us-npi",
          "value": "9876543210"
        },
        "display": "Dr. Sarah Johnson, MD"
      },
      "role": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole",
            "code": "prescribing",
            "display": "Prescribing provider"
          }
        ]
      }
    }
  ],
  "item": [
    {
      "sequence": 1,
      "productOrService": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/ndc",
            "code": "0777-3105-02",
            "display": "Lisinopril 10mg tablets"
          }
        ]
      },
      "servicedDate": "2024-01-15",
      "quantity": {
        "value": 30,
        "unit": "tablets"
      }
    }
  ]
}

#API

GEThttps://api.flexpa.com/fhir/ExplanationOfBenefit/:id

#Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For a full list of available Resources, please refer to the FHIR Resources documentation.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Request path parameters

identifierstring: The identifier of the resource to be retrieved - used in the last part of the URL path segment

Error codes

transient429 status code: The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.; You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
processing422 status code: The API is expected to return a 422 when Flexpa fails to synchronize any resources from the payer for the requested Patient. Please re-authorize or reach out to support.

Request

GET

/fhir/ExplanationOfBenefit/:id

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/ExplanationOfBenefit/f6916af5-d5ec-4aee-8d36-b82cbef14eb0 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GEThttps://api.flexpa.com/fhir/ExplanationOfBenefit

#Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Search parameters

care-teamreference: Member of the CareTeam
claimreference: The reference to the claim
coveragereference: The plan under which the claim was adjudicated
createddate: The creation date for the EOB
detail-udireference: UDI associated with a line item detail product or service
dispositionstring: The contents of the disposition message
encounterreference: Encounters associated with a billed line item
entererreference: The party responsible for the entry of the Claim
facilityreference: Facility responsible for the goods and services
identifiertoken: The business identifier of the Explanation of Benefit
item-udireference: UDI associated with a line item product or service
patientreference: The reference to the patient
payeereference: The party receiving any payment for the Claim
procedure-udireference: UDI associated with a procedure
providerreference: The reference to the provider
statustoken: Status of the instance
subdetail-udireference: UDI associated with a line item detail subdetail product or service

Error codes

transient429 status code: The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.; You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
processing422 status code: The API is expected to return a 422 when Flexpa fails to synchronize any resources from the payer for the requested Patient. Please re-authorize or reach out to support.

Request

GET

/fhir/[Resource]

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/ExplanationOfBenefit \
  -H "Authorization: Bearer $ACCESS_TOKEN"