Explanation of Benefits

Goal

An Explanation of Benefits (EOB) is a statement from a health insurance plan describing what costs will be covered for medical care received (e.g., a medical procedure or a prescription) by a covered person. EOBs are typically created when providers such as hospitals, medical clinics or pharmacies submit a claim on behalf of a covered person to their health insurance plan.

We will use Flexpa Link and Flexpa API together to retrieve EOBs. A history of EOBs can aid in workflows such as recommending the best health insurance plans during enrolment periods.

Getting started

EOBs are directly represented in patient access APIs as a FHIR Resource. We can make HTTP requests to Flexpa API to search for and find EOBs belonging to a particular patient. Patients authorize your app to access their EOBs via Flexpa Link. At the end of the Flexpa Link flow you'll have:

An access token that is required for all requests to Flexpa API
A patient id, that is required to query FHIR resources directly related to the patient

Searching for a Patient's EOB

Flexpa API can be used to search for EOBs after a patient has authorized access via Flexpa Link. 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. To search for EOBs belonging to a particular patient, you must provide a patient value as a query parameter.

You can retrieve the patient id by either:

saving the patient id obtained trough the Flexpa Link flow
introspecting the access token

ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
PATIENT_ID=Patient/A000123 # replace with the patient id you obtained at the end of the Flexpa Link flow

curl "https://api.flexpa.com/fhir/ExplanationOfBenefit?patient=$PATIENT_ID" \
  -H "Authorization: $ACCESS_TOKEN"

Response Type

The return type of querying the EOB endpoint is a searchset bundle. Technically, a searchset bundle may contain different types of resources (e.g., EOBs, Patients, etc) in the entry field. When iterating through entry it is best practice to inspect each resourceType field to ensure you are dealing with the expected resource.

Sample Response

{
  "resourceType": "Bundle",
  "id": "463c09de826e4af1ba1fd16f76afe6f3",
  "meta": {
    "lastUpdated": "2022-06-03T13:26:19.010571+00:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "next",
      "url": "https://fhir.humana.com/sandbox/api/ExplanationOfBenefit?patient=74532b683658335246434e495a53425462476c5741673d3d&ct=er97f5lRTXS1Ukl%2BdmqeklVeaU6OjlJRYl56qpJVtVJuZp6SlZKBqbOhq4GSjlJuYoWSlZKbm1JtbSwAAAD%2F%2Fw%3D%3D"
    },
    {
      "relation": "self",
      "url": "https://fhir.humana.com/sandbox/api/ExplanationOfBenefit?patient=74532b683658335246434e495a53425462476c5741673d3d"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.humana.com/sandbox/api/ExplanationOfBenefit/df4e20433ff8accdd1e689a4f5d018c272fe51c53e54d1bdeffb48a2277314f5",
      "resource": {
        "resourceType": "ExplanationOfBenefit",
        "id": "df4e20433ff8accdd1e689a4f5d018c272fe51c53e54d1bdeffb48a2277314f5",
        "meta": {
          "versionId": "140",
          "lastUpdated": "2022-06-03T07:04:42.795+00:00",
          "source": "https://fhir.humana.com/documentation/glossary/HumanaDataSource",
          "tag": [
            {
              "system": "https://www.hl7.org/fhir/patient.html",
              "code": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
            },
            {
              "system": "https://fhir.humana.com/documentation/glossary/lastRefreshedOn",
              "code": "2022-06-03T07:04:38.564Z"
            }
          ]
        },
        "identifier": [
          {
            "use": "usual",
            "system": "https://fhir.humana.com/documentation/glossary/claim_id",
            "value": "716975276824"
          },
          {
            "system": "https://fhir.humana.com/documentation/glossary/source_data_id",
            "value": "undefined"
          }
        ],
        "status": "active",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",
              "code": "pharmacy",
              "display": "Pharmacy"
            }
          ],
          "text": "Pharmacy"
        },
        "use": "claim",
        "patient": {
          "reference": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
        },
        "created": "2020-06-11",
        "insurer": {
          "display": "Humana"
        },
        "provider": {
          "identifier": {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "7653324343"
          },
          "display": "Alvena Schaden"
        },
        "prescription": {
          "identifier": {
            "system": "http://hl7.org/fhir/sid/ndc",
            "value": "10135036701"
          },
          "display": "prochlorperazine maleate"
        },
        "facility": {
          "display": "52913 Hackett Glens, Jovanymouth ND, 30783"
        },
        "outcome": "complete",
        "insurance": [
          {
            "focal": true,
            "coverage": {
              "identifier": {
                "system": "https://fhir.humana.com/documentation/glossary/memberIdBase",
                "value": "H40183968"
              }
            }
          }
        ],
        "item": [
          {
            "sequence": 1,
            "productOrService": {
              "coding": [
                {
                  "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                  "code": "312635",
                  "display": "prochlorperazine maleate"
                },
                {
                  "system": "http://hl7.org/fhir/sid/ndc",
                  "code": "10135036701",
                  "display": "prochlorperazine maleate"
                }
              ]
            }
          }
        ],
        "total": [
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "allowedamount"
                }
              ]
            },
            "amount": {
              "value": 287.77,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "cobamount"
                }
              ]
            },
            "amount": {
              "value": 0,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "coinsuranceamount"
                }
              ]
            },
            "amount": {
              "value": 0,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "copaymentamount"
                }
              ]
            },
            "amount": {
              "value": 0,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "deductibleamount"
                }
              ]
            },
            "amount": {
              "value": 0,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "noncoveredamount"
                }
              ]
            },
            "amount": {
              "value": 806.8,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "patientpayamount"
                }
              ]
            },
            "amount": {
              "value": 0,
              "currency": "USD"
            }
          },
          {
            "category": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/us/carin/CodeSystem/carin-bb-adjudicationcategory",
                  "code": "paymentamount"
                }
              ]
            },
            "amount": {
              "value": 287.77,
              "currency": "USD"
            }
          }
        ],
        "payment": {
          "type": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBPayerClaimPaymentStatusCode",
                "code": "paid",
                "display": "paid"
              }
            ]
          },
          "date": "2020-06-12",
          "amount": {
            "value": 287.77,
            "currency": "USD"
          }
        }
      },
      "search": {
        "mode": "match"
      }
    },

  ]
}

Notable Fields

An EOB response contains many fields. You can get an exhaustive list and explanation of each field here. Some notable fields:

entry - A collection of EOBs (see response type on best practice of checking resourceType)
meta.lastUpdated - An ISO8601 string representing the last time the bundle was modified
entry[i].resource.type.code[j].code - A claim type string, can have a value of "institution", "oral", "pharmacy", "professional" or "vision"
entry[i].resource.provider - The provider (practitioner or organization) which is responsible for the claim
entry[i].resource.prescription (optional) - The prescription to support the dispensing of pharmacy, device or vision products
entry[i].resource.total[] - Categorized monetary totals for the adjunction
- Includes dollar amount the insurer paid
- Includes dollar amount the patient paid out-of-pocket

Next Steps

Flexpa Link

Flexpa Link is a client-side component to help your users link health plan data sources

Build with Flexpa Link →

API Reference

Use Flexpa API as a unified API to access Explanation of Benefits and more

Build with Flexpa API →