Recover without duplicate work

Keep a request identifier so interrupted connections do not create extra reports or scans.

One idempotency key per intended change

Include an Idempotency-Key when creating reports or committing imports. Use 1–128 letters, numbers, dots, underscores, colons or hyphens. Keep the key with the original request body in your integration.

Idempotency-Key: profiles:batch-2026-001

If the connection drops

1. Retry the same endpoint with the same idempotency key and the same ordered JSON content.
2. If the first attempt committed, Linkwiz returns its saved result with Idempotency-Replayed: true.
3. If it did not commit, the retry can perform the operation once. Do not generate a new key just because a response was lost.

Changing normalized content under a used key returns 409. Row order is significant. A new intentional operation needs a new key. Current authentication and access checks still apply to replays.

Receipt and replay lifetime

Retry results and import receipts are available for 30 days. An expired import receipt returns 410 while its expiry marker remains, then 404 after cleanup. The report and scan results have their own lifecycle. After the retry window, reconcile the report and roster before deciding to send a new operation; do not assume an old retry key still protects against duplicates.

Existing company reports

Report creation defaults to creating another report, even for the same company. Set on_existing: "return_existing" to look up matches instead. When matches exist, 200 returns a list and optional cursor; supplied profiles are not imported into those reports. Choose a report and use its profile-import endpoint.

Scan failures are a separate workflow

Replaying a successful import does not restart its scans. Read the returned scan references and inspect failed, partial, inaccessible or cancelled outcomes in the app. The API does not expose a standalone rescan endpoint.