What is a Claim?

The Claim resource is a request for payment for healthcare services provided to a patient. It includes details about the services, diagnosis, insurance, and items billed.

API convention: the patient is referenced as a flat id (patientId). Provider, insurer and coverage references use the standard FHIR reference shape. All ids are UUIDs.

Create a Claim

curl -X POST https://api.esus.health/fhir/Claim \
  -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",
        "display": "Institutional"
      }]
    },
    "use": "claim",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "billablePeriod": {
      "start": "2026-04-21T09:00:00Z",
      "end": "2026-04-21T10:00:00Z"
    },
    "created": "2026-04-21",
    "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",
          "display": "Acute upper respiratory infection"
        }]
      }
    }],
    "insurance": [{
      "sequence": 1,
      "focal": true,
      "coverage": {
        "reference": "Coverage/c1a2e3d4-5b6f-7890-abcd-ef1234567890"
      }
    }],
    "item": [{
      "sequence": 1,
      "productOrService": {
        "coding": [{
          "system": "http://www.ama-assn.org/go/cpt",
          "code": "99213",
          "display": "Office visit, established patient"
        }]
      },
      "quantity": { "value": 1 },
      "unitPrice": { "value": 150.00, "currency": "USD" }
    }]
  }'

Claim Types (typical)

Claim Statuses (ESUS-side lifecycle)

The ESUS status tracks the claim’s lifecycle on the platform. Adjudication outcomes (approved, denied, partial) are returned in the associated ClaimResponse via its outcome and decision fields — see the next page.

Use

Supporting Documentation

Attach supporting documents by uploading them via /files/upload and then creating a DocumentReference that links to the claim (via the DocumentReference.context.related field or through your own cross-reference).