# Event sample: `claims.status-changed`

> Fictional training artifact — synthetic sample. Shows what an
> **event-driven** integration contract looks like, in contrast to the
> request-response Claims API. Referenced by wiki ch 02, 06 and 08.

When a claim changes status in the core claims system, an event is published to the
`claims.status-changed` topic. The partner portal subscribes so partners see status
updates without polling `GET /claims/{claimId}` every few minutes.

## Event example

```json
{
  "eventId": "f2b9a7d0-4c1e-4e8a-9b6f-2d8c5a1e7f33",
  "eventType": "ClaimStatusChanged",
  "eventVersion": "1.0",
  "occurredAt": "2026-06-08T09:15:42Z",
  "source": "coresure-claims",
  "data": {
    "claimId": "CLM-2026-000871",
    "policyNumber": "MTPL-2026-104782",
    "previousStatus": "REGISTERED",
    "newStatus": "UNDER_REVIEW",
    "statusReason": null
  }
}
```

## Field reference

| Field | Type | Notes |
|-------|------|-------|
| `eventId` | UUID | Unique per event. **Consumers de-duplicate on this** (see delivery semantics). |
| `eventType` | string | Always `ClaimStatusChanged` on this topic. |
| `eventVersion` | string | Schema version of the event payload. |
| `occurredAt` | ISO 8601 UTC | When the change happened in the core claims system, not when delivered. |
| `source` | string | Publishing system identifier. |
| `data.claimId` | string | Same format as Claims API (`CLM-YYYY-NNNNNN`). |
| `data.previousStatus` / `data.newStatus` | enum | Same `ClaimStatus` values as the Claims API: REGISTERED, UNDER_REVIEW, APPROVED, REJECTED, CLOSED. |
| `data.statusReason` | string or null | Filled for REJECTED / CLOSED. |

## Delivery semantics (the part analysts must not skip)

- **At-least-once delivery.** The same event **can arrive twice** (e.g., after
  a broker retry). Consumers must treat redelivery as normal: process each
  `eventId` only once. This is a *requirement* for any consumer you specify.
- **Ordering** is guaranteed only per claim (events for one `claimId` arrive
  in order; events for different claims may interleave).
- **Retention:** events are kept 7 days. A consumer that was down longer must
  re-sync via `GET /claims` instead of replaying the topic.
- **No personal data** in events by design (data minimisation): no claimant
  name/contacts - consumers fetch details via the API if entitled.

## What to capture in requirements when a consumer subscribes

1. Which statuses trigger consumer action (all transitions, or e.g. only APPROVED/REJECTED?)
2. De-duplication behaviour (idempotent processing on `eventId`)
3. What the consumer does if events stop arriving (staleness alert after X minutes?)
4. Catch-up procedure after downtime > retention