> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt
> Use this file to discover all available pages before exploring further.

# Claims

> Collect alerts into a claim, send it to the supplier and record what you get back.

A claim is what you send a supplier when they have charged too much. It collects
[alerts](/api-reference/alerts) from one agreement, tracks the claim from start to finish, and records
the money you get back.

## Create a claim

Create the claim and add alerts in the same request. This example claims every pending alert in one
topic:

```bash theme={null}
curl "$API_URL/v1/claims" \
  -H "Authorization: Bearer $API_KEY" -H "X-Organization-Id: $ORGANIZATION_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"agreement_id\": \"$AGREEMENT_ID\",
    \"title\": \"Freight surcharges\",
    \"alerts\": {\"filter\": {\"topic_ids\": [\"$TOPIC_ID\"], \"statuses\": [\"pending\"]}}
  }"
```

You can also list the alerts by `alert_ids`. Pending alerts you add become **claimed**. An alert can
only be in one claim at a time.

## Add and remove alerts

* `POST /v1/claims/{id}/alerts` adds alerts.
* `POST /v1/claims/{id}/alerts/remove` takes them out again. Claimed alerts go back to pending.
* Set `move_from_open_claims: true` when adding to move alerts from pending or in-progress claims
  in the same transaction. Completed and cancelled source claims are excluded.

Each takes `alert_ids` or a `filter`, just like creating a claim. To see what's in a claim, list
alerts with `GET /v1/alerts?claim_ids=$CLAIM_ID`.

## Follow a claim through

A claim is `pending`, `in_progress`, `completed` or `cancelled`. Change it with
`PATCH /v1/claims/{id}`:

```json theme={null}
{ "status": "in_progress" }
```

* Once a claim is **completed**, its alerts can't be changed. Reopen it first if you need to.
* **Cancelling** a claim dismisses its pending and claimed alerts. Credited alerts stay credited.

The claim's `summary` shows the number of alerts and their impact by status. Use `summary.claimed`
for the amount you are claiming. Amounts are per currency and are never converted.

## Send it to the supplier

`GET /v1/claims/{id}/export?format=pdf` returns a claim document you can send to the supplier. Use
`format=xlsx` or `format=csv` for every alert as a row. Claimed alerts are always included; add
`include_pending=true` or `include_credited=true` to include those too.

```bash theme={null}
curl --get "$API_URL/v1/claims/$CLAIM_ID/export" \
  -H "Authorization: Bearer $API_KEY" -H "X-Organization-Id: $ORGANIZATION_ID" \
  --data-urlencode 'format=pdf' \
  --output claim.pdf
```

`GET /v1/claims/{id}/documents` lists the invoice files behind the claim, if you want to send them
along.

## Record what you get back

When the supplier pays back or credits money, record it as a **refund** with
`POST /v1/claims/{id}/refunds`, giving the amount and currency. The claim's `refund_summary` adds up
the refunds per currency. To see what was recovered in a period, such as this year, call
`GET /v1/claims/metrics` with `refunded_from` and `refunded_through`: its `refund_summary` then counts
only refunds recorded in that period.

If the supplier sends a credit note, attach it with `POST /v1/claims/{id}/credit-notes`. Set
`"create_refund": true` to record a refund for the credit note's amount at the same time. A credit
note on its own is just evidence: only refunds count as money received.

## Delete a claim

`DELETE /v1/claims/{id}?alert_outcome=pending` removes a claim for good. Choose with the query parameter `alert_outcome` whether its
claimed alerts go back to `pending` or are `dismissed`. To keep a record of the claim, cancel it
instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.