Claims And Payouts

# Claims And Payouts

Claims and payouts are where the Auk protection lifecycle resolves into real
operational action.

## Canonical Shape

```text
trigger observed
  -> claim opened
  -> claim approved or deferred
  -> payout released, blocked, or reconciled later
```

## Public Boundary

This page should explain the durable external posture without exposing private
internal adjudication logic.

That means the public contract should be clear about:

- when a claim exists
- what approved versus deferred means
- what payout release represents
- how payout state is tracked independently from browser UI

## Claim Creation And Read Model

The core claim group starts with:

- `POST /claims`
- `GET /claims/{claim_id}`
- `GET /claims/{claim_id}/timeline`

Those endpoints are the public anchors for opening a claim, reading its current
state, and inspecting lifecycle progression without depending on the console as
the authority.

## Claim Collaboration And Evidence

Operational claim work also needs durable collaboration surfaces:

- `POST /claims/{claim_id}/attachments`
- `GET /claims/{claim_id}/attachments`
- `POST /claims/{claim_id}/messages`
- `GET /claims/{claim_id}/messages`

These reads and writes give the API tab a real anchor for evidence and
partner-visible claim collaboration.

## Payout Release And Beneficiary Methods

Payout release becomes concrete through beneficiary-method recording:

- `POST /payout_methods`
- `GET /claims/{claim_id}/payout-methods`

This section is the anchor for the API tab whenever the current docs context is
about payout destinations, release posture, or beneficiary verification.

## Why Claims And Payouts Stay Paired

Partners usually need both concepts together:

- claims explain *why* the lifecycle advanced
- payouts explain *what happened* after approval

Keeping them paired gives the API tab a stable anchor for later endpoint
grouping and contextual highlighting.

## What Deepens Later

- claim object summaries
- payout state machine details
- reconciliation and failure semantics
- support and escalation boundaries