> ## 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.

# Explicit invoice–agreement matching

> Refresh relationships, inspect results, and retry unfinished invoices.

Refresh an invoice's agreement relationships, or discover invoices for one agreement. Matching
uses supplier and recipient coverage, dates and invoice-line periods, agreement status, filters,
and optional smart criteria. Financial validity and human approval do not exclude invoices.

```bash theme={null}
curl -i -X POST "$WATCHDOG_API_URL/v1/invoices/$INVOICE_ID/match-agreements" \
  -H "Authorization: Bearer $WATCHDOG_API_KEY" \
  -H "X-Organization-Id: $WATCHDOG_ORG_ID" \
  -H "Idempotency-Key: invoice-refresh-2026-09-10"
```

For an agreement, use `POST /v1/agreements/{id}/match-invoices` with the same headers. No request
body is required. New work returns `202` and `workflow_run_id` after execution acceptance, with
`Location` pointing to its run. Idempotent replays return `200`
with the original identity. If acceptance is unconfirmed, inspect the run in the error's `Location`.
Replaying an idempotency key does not dispatch again; use a fresh key for a new attempt.

Each fresh command supersedes active matching for the same target. Published relationships remain;
the new run rechecks hard filters and reuses unchanged positive smart decisions.

Follow [workflow runs and items](/api-preview/workflow-runs) for progress and cancellation.
Each item identifies one invoice. An invoice refresh has one item; an agreement refresh discovers
invoice items and leaves `progress.total` unknown until discovery closes. Zero matching candidates
can complete successfully. Each successful invoice publishes independently; failed invoices retain
their previous relationships. Item results contain matched, created, and removed counts, up to 100
relationship IDs, and a link to the full paginated collection.

```bash theme={null}
curl "$WATCHDOG_API_URL/v1/invoices/$INVOICE_ID/agreements?limit=50" \
  -H "Authorization: Bearer $WATCHDOG_API_KEY" \
  -H "X-Organization-Id: $WATCHDOG_ORG_ID"
```

Use `GET /v1/agreements/{id}/invoices` for the reverse direction. Both collections include stable
relationship IDs, invoice and agreement IDs, timestamps, and bounded resource summaries. Follow
`next_cursor` until it is null. Pages default to 50 and allow at most 100, ordered by relationship
creation time and UUID ascending. Cursors are bound to the organization and target.

Archived agreement relationships remain readable. Deleted resources follow the usual resource
visibility rules. Inactive agreements preserve existing relationships. Reads use persisted matches
and agree with invoice agreement filters and match counts.

Unchanged positive smart decisions can be reused. Changed configuration or invoice evidence
requires evaluation. New commands with changed target inputs replace active API work for that
same target. Cancellation preserves completed items and other targets' runs. After failure,
partial failure, or cancellation, a fresh command uses current inputs and links unsuccessful
predecessors; technical retries keep their identities.

Reads require Read. Matching and cancellation require Write, using the same organization, role,
and ownership checks as other endpoints. Matching does not approve invoices or start compliance
checks. When it removes a match, the pair's alerts are deleted, unless a claim that is not cancelled holds one of them that is not dismissed, and its
unfinished checks are cancelled; completed compliance checks are kept. Saving a resource does not start matching automatically.