Coverage

Coverage is a standalone FHIR resource with full CRUD at /fhir/Coverage. It represents a patient’s insurance coverage: who the beneficiary is, who pays (the payor), the plan, and its effective period. Other financial resources reference it by Coverage/<uuid> — for example Claim.insurance[].coverage and Account.coverage[].coverage.

API convention: the beneficiary is a flat id (beneficiaryId); payor is an array of FHIR references and is required; subscriber, policyHolder, and contract use the standard FHIR reference shape. All ids are UUIDs.

Create a Coverage

beneficiaryId and payor are the only required fields. status is optional and defaults to active.

curl -X POST https://api.esus.health/fhir/Coverage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "active",
    "beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payor": [
      { "reference": "Organization/9a8b7c6d-5e4f-3210-9876-543210fedcba" }
    ],
    "subscriberId": "MEMBER-12345",
    "relationship": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
        "code": "self"
      }]
    },
    "period": { "start": "2026-01-01", "end": "2026-12-31" },
    "class": [
      {
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
            "code": "plan"
          }]
        },
        "value": "HMO-GOLD",
        "name": "Blue Cross Blue Shield — HMO Gold"
      }
    ],
    "order": 1
  }'

Read, Update, and Delete

# Read by id
curl "https://api.esus.health/fhir/Coverage/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update (PUT replaces; PATCH applies partial changes)
curl -X PATCH "https://api.esus.health/fhir/Coverage/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{ "status": "cancelled" }'

# Delete
curl -X DELETE "https://api.esus.health/fhir/Coverage/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_TOKEN"

Version history is also available at /fhir/Coverage/:id/_history and /fhir/Coverage/:id/_history/:vid.

Search Coverages

Supported search parameters: patient (or beneficiary), status, type, payor, subscriber.

# All active coverages for a patient
curl "https://api.esus.health/fhir/Coverage?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Coverages for a payor
curl "https://api.esus.health/fhir/Coverage?payor=Organization/9a8b7c6d-5e4f-3210-9876-543210fedcba" \
  -H "Authorization: Bearer YOUR_TOKEN"

Referencing Coverage from Claim and Account

Once a Coverage exists, reference it by Coverage/<uuid> wherever adjudication is needed.

On a Claim, each insurance[] entry points to a coverage; exactly one must have focal: true (the primary coverage):

{
  "resourceType": "Claim",
  "insurance": [
    {
      "sequence": 1,
      "focal": true,
      "coverage": {
        "reference": "Coverage/3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "display": "Blue Cross Blue Shield — HMO Gold"
      },
      "preAuthRef": ["PA-2026-12345"]
    }
  ]
}

On an Account, coverage[] lists the coverages backing the account, each with its priority:

{
  "resourceType": "Account",
  "coverage": [
    {
      "coverage": { "reference": "Coverage/3fa85f64-5717-4562-b3fc-2c963f66afa6" },
      "priority": 1
    }
  ]
}