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. Data types used in this reference are defined in the FHIR R4 Data Types specification.

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 a guide to claims?

Claims Guide

Comprehensive guide to understanding and working with claims data

Read the Claims Guide →Soon

#Schema

#All Claims

The FHIR R4 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.

The EOB FHIR Resource specification has a comprehensive set of data elements, but not all of them are used in practice in the context of Flexpa's EOBs nor of the CARIN Blue Button® Framework. This reference documentation focuses on the most commonly used and relevant elements.

Claims are structured with two main components: header-level elements that describe the overall claim, and item-level elements that detail individual services, procedures, or products. The elements documented below are all header-level elements that apply to the entire claim.

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

metaMeta: Metadata about the resource. See also Tags defined by Flexpa.
lastUpdatedinstant: The last time the claim was updated or the date of creation in the payer’s system of record
identifierIdentifier: Business identifiers assigned to 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
EOB is active and ready for use
cancelled
EOB has been cancelled
draft
EOB is a draft - not required to be published by CMS-9115
entered-in-error
EOB 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 prescription medications and pharmacy 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 and is the default value for all 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 - this is synonymous with the beneficiary or covered person but not necessarily the subscriber or policy holder
billablePeriodPeriod: The period for which services are being billed
createddate: The date the EOB was created
insurerReference(Organization): Reference to the payer who is responsible for the EOB / insurance company behind the claim - see also the EndpointId tag provided by Flexpa
providerReference(Practitioner|Organization): Reference to the provider who delivered the service
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
outcomecode: The outcome of the claim processing - see also status for the status of the EOB as a resource and payment.type for the adjudication status; 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
careTeamarray: Care team members involved in the delivery of the service - see also the type-specific careTeam elements below
providerReference(Practitioner|Organization): Reference to the provider who delivered the service
insuranceBackboneElement: Patient insurance information
focalboolean: Indicates the Coverage is to be used for adjudication
coverageReference(Coverage): Reference to the Coverage to be used for adjudication
totalarray: Financial summary by category (submitted, allowed, paid, etc.). See our Financial Data Guide for more details.
paymentBackboneElement: Details about the status of the payment for the claim
typeCodeableConcept: Indicates the status of the payment for the claim - see also outcome for the status of the claim processing and status for the status of the EOB as a resource; 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",
  "meta": {
    "lastUpdated": "2023-01-01T00:00:00Z"
  },
  "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" },
  "billablePeriod": {
    "start": "2023-01-01",
    "end": "2023-01-31"
  },
  "created": "2023-01-01",
  "insurer": { "reference": "Organization/example" },
  "provider": { "reference": "Practitioner/example" },
  "payee": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBPayeeType",
          "code": "beneficiary"
        }
      ]
    },
    "party": { "reference": "Patient/example" }
  },
  "outcome": "complete",
  "careTeam": [
    {
      "sequence": 1,
      "provider": { "reference": "Practitioner/example" },
    }
  ],    
  "insurance": {
    "focal": true,
    "coverage": { "reference": "Coverage/example" }
  },
  "total": [
    {
      "category": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/adjudication",
            "code": "submitted"
          }
        ]
      },
      "amount": { "value": 1000, "currency": "USD" }
    }
  ],    
  "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-CM codes for diagnoses, and ICD-10-PCS codes for inpatient procedures. They are also a source for DRG codes, Type of Bill, Present on Admission, Point or Origin, and other NUBC codes.

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

subTypeCodeableConcept: Granular institutional claim subtype; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBInstitutionalClaimSubType
CARIN Blue Button-defined institutional claim subtypes
Codes
inpatient
Inpatient institutional claim
outpatient
Outpatient institutional claim
careTeamarray: Care team members involved in the delivery of the institutional claim
roleCodeableConcept: Role of the care team member; Systemhttp://terminology.hl7.org/CodeSystem/claimcareteamrole
An HL7 standard code for the role of the care team member
Codes
primary
Primary care team member; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole
CARIN Blue Button-defined care team roles for institutional claims
Codes
attending
Attending physician
referring
Referring physician
operating
Operating physician
otheroperating
Additional operating physician
performing
Performing or rendering physician
qualificationCodeableConcept: Credential or specialization of the care team member - only used for outpatient institutional claims; Systemhttp://nucc.org/provider-taxonomy
NUCC Health Care Provider Taxonomy Code Set for providers
Codes
diagnosisBackboneElement: The patients's principal condition treated during this service corresponding to UB-04 Form Locator 67. This may or may not be different from the admitting diagnosis.
typeCoding: Type of diagnosis (principal, other, etc.) - see also diagnosisCodeableConcept for the diagnosis codes themselves; Systemhttp://terminology.hl7.org/CodeSystem/ex-diagnosistype
HL7 diagnosis types
Codes
principal
Primary diagnosis most relevant to treatment (UB-04 Form Locator 67)
admitting
Reason for hospital admission - inpatient only (UB-04 Form Locator 69); Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimDiagnosisType
Additional CARIN Blue Button diagnosis types
Codes
other
Required when other conditions coexist or develop subsequently during the treatment
externalcauseofinjury
Required when an external cause is needed to describe an injury
patientreasonforvisit
Identifies the patient's reason for an outpatient institutional visit
diagnosisCodeableConceptCodeableConcept: Diagnosis code itself (ICD-10-CM or ICD-9-CM); Systemhttp://hl7.org/fhir/sid/icd-10-cm
ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification) 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
ICD-9-CM (International Classification of Diseases, 9th Revision, Clinical Modification) codes used for diagnosis coding in the United States.
Example Codes
V70.0
Routine medical examination
onAdmissionCodeableConcept: Present On Admission Indicator Codes are represented as "FL 67 - Present on Admission" in CMS-1450 / UB-04. They are used to report whether or not a condition was present on admission and act as modifiers to further define diagnosis codes.; Systemhttps://www.nubc.org/CodeSystem/PresentOnAdmissionIndicator
These codes are listed within the UB-04 Data Specifications Manual
Example Codes
Y
Present at the time of inpatient admission
procedureBackboneElement: Clinical procedures performed - only used for inpatient institutional claims
typeCodeableConcept: Category of procedure - see also procedureCodeableConcept for the specific procedure code itself; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimProcedureType
Indicates if the inpatient institutional procedure (ICD-PCS) is the principal procedure or another procedure
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-PCS (International Classification of Diseases, 10th Revision, Procedure Coding System) - 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
ICD-9-CM (International Classification of Diseases, 9th Revision, Procedure Coding System) procedure codes - published by CMS for classifying procedures performed in hospital inpatient health care settings
Example Codes
45.13
Other endoscopy of small bowel
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
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
CMS-1450 / UB-04 Source of Admission (FL-15) identifies the place where the patient was identified as needing admission to a facility
typeofbill
CMS-1450 / 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
CMS-1450 / UB-04 Priority (Type) of Admission or Visit (FL-14) indicates the priority of an admission
discharge-status
CMS-1450 / 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 - these codes are listed within the UB-04 Data Specifications Manual
Example Codes
1
Non-health care facility point of origin; Systemhttps://www.nubc.org/CodeSystem/TypeOfBill
Used when category = typeofbill - these codes are listed within the UB-04 Data Specifications Manual
Example Codes
111
Hospital Inpatient - Admit thru Discharge Claim; Systemhttps://www.nubc.org/CodeSystem/PriorityTypeOfAdmitOrVisit
Used when category = admtype - these codes are listed within the UB-04 Data Specifications Manual
Example Codes
1
Emergency; Systemhttps://www.nubc.org/CodeSystem/PatDischargeStatus
Used when category = discharge-status - these codes are listed within the UB-04 Data Specifications Manual
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 are a key source for CPT and HCPCS codes for procedures and services, ICD-10-CM and ICD-9-CM codes for diagnoses, and ICD-10-PCS codes for professional procedures.

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

careTeamarray: Care team members involved in the delivery of the professional claim
roleCodeableConcept: Role of the care team member; Systemhttp://terminology.hl7.org/CodeSystem/claimcareteamrole
An HL7 standard code for the role of the care team member
Codes
primary
Primary care provider
supervisor
Supervising care provider; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole
CARIN Blue Button-defined care team roles for institutional claims
Codes
performing
Performing or rendering physician
referring
Referring physician
purchasedservice
Purchased service from another provider
qualificationCodeableConcept: Credential or specialization of the care team member; Systemhttp://nucc.org/provider-taxonomy
NUCC Health Care Provider Taxonomy Code Set for providers
Codes
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
secondary
Required when necessary to report additional diagnoses on professional and non-clinician claims
diagnosisCodeableConceptCodeableConcept: Diagnosis code itself (ICD-10-CM or ICD-9-CM); Systemhttp://hl7.org/fhir/sid/icd-10-cm
ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification) 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
ICD-9-CM (International Classification of Diseases, 9th Revision, Clinical Modification) codes used for diagnosis coding in the United States.
Example Codes
V70.0
Routine medical examination
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)
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 and pharmacy-specific transaction details like days supply, refill information, and prescriber instructions.

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

NCPDP (National Council for Prescription Drug Program) Transactions - National Council for Prescription Drug Programs electronic transaction standards

Elements

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
itemarray: Medication dispensed
productOrServiceCoding: Drug code - or compound code indicator; Systemhttp://hl7.org/fhir/sid/ndc
National Drug Code (NDC) - FDA's unique identifier for drug packages
Example Codes
68180-0980-30
Lisinopril oral tablet, Lupin, 10 mg, bottle, 5000 count; Systemhttp://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBCompoundLiteral
CARIN Blue Button-defined compound literal code
Codes
compound
Compound drug
servicedDatedate: Date when the medication was dispensed
quantityQuantity: Quantity of medication dispensed
detailBackboneElement: Additional details about the medication dispensed
productOrServiceCoding: When the item.productOrService is compound, this is the NDC of the compounded drug; Systemhttp://hl7.org/fhir/sid/ndc
National Drug Code (NDC) - FDA's unique identifier for drug packages
Example Codes
68180-0980-30
Lisinopril oral tablet, Lupin, 10 mg, bottle, 5000 count
quantityQuantity: Quantity of medication dispensed
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"