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.