ClaimResponse
When a payer processes a claim, they return a ClaimResponse with adjudication details — what was paid, denied, or adjusted.
API convention: the patient is a flat id (
patientId); the originating claim is a flat id (claimId); insurer and requestor use the standard FHIR reference shape. All ids are UUIDs.
Create (or Ingest) a ClaimResponse
curl -X POST https://api.esus.health/fhir/ClaimResponse \
-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"
},
"claimId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
"outcome": "complete",
"total": [{
"category": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/adjudication",
"code": "benefit",
"display": "Benefit Amount"
}]
},
"amount": { "value": 1200.00, "currency": "USD" }
}],
"item": [{
"itemSequence": 1,
"adjudication": [
{ "category": { "coding": [{ "code": "submitted" }] }, "amount": { "value": 150.00, "currency": "USD" } },
{ "category": { "coding": [{ "code": "eligible" }] }, "amount": { "value": 120.00, "currency": "USD" } },
{ "category": { "coding": [{ "code": "benefit" }] }, "amount": { "value": 96.00, "currency": "USD" } },
{ "category": { "coding": [{ "code": "copay" }] }, "amount": { "value": 24.00, "currency": "USD" } }
]
}]
}'
Outcome vs Status
| Field | Values | Meaning |
|---|---|---|
status | draft, active, cancelled, entered-in-error | Platform lifecycle of the response record |
outcome | queued, complete, partial, error | Adjudication result returned by the payer |
use | claim, preauthorization, predetermination | What kind of response this is |
Common Adjudication Categories
| Category | Meaning |
|---|---|
submitted | Amount submitted on the claim |
eligible | Maximum amount allowed by the payer |
benefit | Amount paid by the payer |
patientpay | Amount the patient is responsible for |
deductible | Amount applied to deductible |
coinsurance | Patient coinsurance amount |
copay | Patient copay amount |
Search and Handle Denials
# Responses for a given claim
curl "https://api.esus.health/fhir/ClaimResponse?request=Claim/aa11bb22-cc33-dd44-ee55-ff6677889900" \
-H "Authorization: Bearer YOUR_TOKEN"
# Responses with adjudication error
curl "https://api.esus.health/fhir/ClaimResponse?outcome=error" \
-H "Authorization: Bearer YOUR_TOKEN"
Denial reasons live in error[] with codes from the payer; rejection rationale lives in disposition or processNote[]. To appeal, create a new Claim with related.claim pointing to the original and attach supporting documentation.