Claims Service — Event Schemas

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW · Service Template · 02 DDD

Events Produced

All events use CloudEvents v1.0 envelope with tenantid, actorid, and correlationid extensions.

Event Type	NATS Subject	Description
claims.claim.created.v1	claims.claim.created	New claim assembled from encounter
claims.claim.submitted.v1	claims.claim.submitted	Claim sent to clearinghouse/payer
claims.claim.accepted.v1	claims.claim.accepted	Positive acknowledgement received
claims.claim.denied.v1	claims.claim.denied	Denial received via remittance
claims.claim.paid.v1	claims.claim.paid	Full payment applied from ERA
claims.claim.appealed.v1	claims.claim.appealed	Appeal filed for denied claim
claims.remittance.received.v1	claims.remittance.received	ERA received and parsed
claims.remittance.applied.v1	claims.remittance.applied	ERA allocations posted to claims
claims.coverage.created.v1	claims.coverage.created	New coverage record created
claims.coverage.updated.v1	claims.coverage.updated	Coverage record modified
claims.eligibility.verified.v1	claims.eligibility.verified	Real-time eligibility check complete
claims.auth.approved.v1	claims.auth.approved	Prior authorization approved by payer

Events Consumed

Event Type	Source Service	Why
billing.charge.finalized.v1	billing-service	Trigger claim assembly when charges are finalized for encounter
scheduling.encounter.closed.v1	scheduling-service	Signal that encounter documentation is complete; eligible for claim assembly

---

Payload Schemas

claims.claim.created.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.claim.created.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T10:00:00Z",
  "tenantid": "tenant_acme",
  "actorid": "usr_billing_staff_01",
  "correlationid": "corr_01HXY...",
  "data": {
    "claimId": "clm_01HXY...",
    "patientId": "pat_01HXY...",
    "encounterId": "enc_01HXY...",
    "coverageId": "cov_01HXY...",
    "totalBilled": { "amount": 275.00, "currency": "USD" },
    "diagnosisCodes": ["J06.9"],
    "lineItemCount": 2
  }
}

---

claims.claim.submitted.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.claim.submitted.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T10:01:00Z",
  "tenantid": "tenant_acme",
  "actorid": "system",
  "correlationid": "corr_01HXY...",
  "data": {
    "claimId": "clm_01HXY...",
    "channel": "x12_837",
    "clearinghouseRef": "CHX-2026-00123",
    "submittedAt": "2026-04-18T10:01:00Z"
  }
}

---

claims.claim.denied.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.claim.denied.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T15:00:00Z",
  "tenantid": "tenant_acme",
  "actorid": "system",
  "correlationid": "corr_01HXY...",
  "data": {
    "claimId": "clm_01HXY...",
    "denialId": "dnl_01HXY...",
    "denialCode": "CO-97",
    "denialReason": "Payment included in another claim",
    "remittanceId": "rem_01HXY...",
    "appealDeadline": "2026-05-18"
  }
}

---

claims.remittance.applied.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.remittance.applied.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T16:00:00Z",
  "tenantid": "tenant_acme",
  "actorid": "system",
  "correlationid": "corr_01HXY...",
  "data": {
    "remittanceId": "rem_01HXY...",
    "payerId": "pyr_01HXY...",
    "totalPaid": { "amount": 198.50, "currency": "USD" },
    "claimsAffected": [
      { "claimId": "clm_01HXY...", "amountPaid": 198.50, "adjustments": [...] }
    ],
    "eobIds": ["eob-fhir-id-1"]
  }
}

---

claims.coverage.created.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.coverage.created.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T09:00:00Z",
  "tenantid": "tenant_acme",
  "actorid": "usr_registration_01",
  "correlationid": "corr_01HXY...",
  "data": {
    "coverageId": "cov_01HXY...",
    "patientId": "pat_01HXY...",
    "payerId": "pyr_01HXY...",
    "priority": "primary",
    "effectiveFrom": "2026-01-01",
    "effectiveTo": null
  }
}

---

claims.eligibility.verified.v1

{
  "specversion": "1.0",
  "id": "01HXY...",
  "source": "claims-service",
  "type": "claims.eligibility.verified.v1",
  "datacontenttype": "application/json",
  "time": "2026-04-18T08:00:00Z",
  "tenantid": "tenant_acme",
  "actorid": "system",
  "correlationid": "corr_01HXY...",
  "data": {
    "eligibilityId": "elig_01HXY...",
    "coverageId": "cov_01HXY...",
    "patientId": "pat_01HXY...",
    "status": "active",
    "channel": "x12_270",
    "expiresAt": "2026-04-19T00:00:00Z"
  }
}

---

NATS JetStream Configuration

stream:
  name: CLAIMS
  subjects:
    - claims.>
  retention: limits
  max_age: 168h        # 7 days
  max_bytes: 10GB
  storage: file
  replicas: 3
  discard: old

consumers:
  - name: billing-service-sub
    filter_subject: claims.remittance.applied.>
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 5
    ack_wait: 30s

  - name: patient-portal-sub
    filter_subject: claims.coverage.> claims.claim.paid.> claims.remittance.applied.>
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 5
    ack_wait: 30s

  - name: population-health-sub
    filter_subject: claims.claim.denied.> claims.remittance.applied.>
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 5
    ack_wait: 30s