Idempotency

Create requests require an Idempotency-Key so a retried request never creates a duplicate candidate.

POST /candidates is the only endpoint that requires an Idempotency-Key header — every other write is naturally idempotent (a PATCH you replay just writes the same values again).

• Required. 1–255 characters. We recommend your own ATS record id.
• Matches on the key ALONE, scoped to your account — the request body is not compared, so replaying with a different body still returns the ORIGINAL result.
• A request with the same key already in flight (not yet finished) gets a 409 — retry after a short delay rather than assuming failure.
• A claimed key that never finishes (your request died mid-flight) is released after 5 minutes — retry with the SAME key past that point.
• A genuinely failed create (4xx/5xx) releases the key immediately — retry right away with the same key.

The key you sent comes back on every later GET /candidates/{id} as external_id, so you never need to keep your own mapping table from your ids to ours.

Idempotency-Key is also OPTIONAL on POST /candidates/{id}/messages and POST /candidates/{id}/references. Send it and an HTTP retry after a timeout replays the first outcome (the original status and body, with replayed: true inside data) instead of sending the same WhatsApp or creating the same reference request twice. It is scoped to your account, that route and that candidate, so one key on two routes or two candidates never collides. A duplicate that arrives while the first is still in flight gets a 409; a request that fails releases the key at once.