What is ExplanationOfBenefit?
ExplanationOfBenefit (EOB) is the authoritative, per-patient statement of how a claim was adjudicated. It combines claim details, adjudication, coverage, and payments into a single record that downstream consumers (patient portal, payer systems, accounting) can trust.
API convention: the patient is a flat id (
patientId); the originating claim is a flat id (claimId); insurer, provider, coverage, and careTeam references use the standard FHIR reference shape. All ids are UUIDs.
Create an EOB
curl -X POST https://api.esus.health/fhir/ExplanationOfBenefit \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/fhir+json" \
-d '{
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "institutional"
}]
},
"use": "claim",
"patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created": "2026-04-22T10:00:00Z",
"insurer": {
"reference": "Organization/9a8b7c6d-5e4f-3210-9876-543210fedcba"
},
"provider": {
"reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789"
},
"claimId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
"outcome": "complete",
"careTeam": [{
"sequence": 1,
"provider": {
"reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789"
}
}],
"diagnosis": [{
"sequence": 1,
"diagnosisCodeableConcept": {
"coding": [{ "system": "http://hl7.org/fhir/sid/icd-10", "code": "J06.9" }]
}
}],
"item": [{
"sequence": 1,
"productOrService": {
"coding": [{ "system": "http://www.ama-assn.org/go/cpt", "code": "99213" }]
},
"adjudication": [
{ "category": { "coding": [{ "code": "submitted" }] }, "amount": { "value": 150.00, "currency": "USD" } },
{ "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 96.00, "currency": "USD" } }
]
}],
"total": [
{ "category": { "coding": [{ "code": "submitted" }] }, "amount": { "value": 150.00, "currency": "USD" } },
{ "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 120.00, "currency": "USD" } }
],
"payment": {
"date": "2026-04-25",
"amount": { "value": 96.00, "currency": "USD" }
}
}'
Outcome vs Status
| Field | Values | Meaning |
|---|---|---|
status | draft, active, cancelled, entered-in-error | Platform lifecycle |
outcome | queued, complete, partial, error | Result of adjudication reflected in this EOB |
use | claim, preauthorization, predetermination | What this EOB explains |
Typical Totals
| Category | Meaning |
|---|---|
submitted | Total billed |
eligible | Total allowed by the payer |
benefit | Total paid by the payer |
patientpay | Total patient responsibility |
deductible, coinsurance, copay | Breakdown of patient responsibility |
Retrieve Patient EOBs
# All EOBs for a patient
curl "https://api.esus.health/fhir/ExplanationOfBenefit?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer YOUR_TOKEN"
# EOBs for a specific date range
curl "https://api.esus.health/fhir/ExplanationOfBenefit?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&created=ge2026-01-01&created=le2026-01-31" \
-H "Authorization: Bearer YOUR_TOKEN"
Patient-Friendly Rendering
Patient-facing EOBs are typically produced by rendering the structured resource into a PDF and storing the PDF via /files/upload, then linking it from a DocumentReference with type = LOINC 89234-4 (“Health insurance explanation of benefits”). There is no separate $patient-friendly operation — rendering happens in your application and the resulting PDF is stored and referenced like any other clinical document.