One key for one intended operation
POST screenings and POST batches require an Idempotency-Key containing 8 to 128 URL-safe letters, digits, underscores, colons, periods, or hyphens. Generate it when your application creates the intended operation and store it with that business record.
Reusing the key with the same normalized request replays the accepted result or batch. Reusing it with different content or a different operation conflicts. Scope is the organization and environment. A fresh key expresses a new screening intent, even if the submitted name happens to be the same.
Recover after an uncertain response
A connection can fail after the database commits. Retry with the original key and body so the server can find the accepted operation. Do not use a new key merely because your client did not receive the first response. Successful screening evidence, usage, and the receipt are committed together.
Retained evidence and idempotency history are different concerns. If the original evidence has expired, the server cannot promise a full replay. Keep the resulting ID and retention policy with your client record. Minimal retention deliberately limits what can be recovered later.
Do not assume every endpoint shares this contract
The required replay contract applies to screening and batch acceptance. A monitor creation, team invitation, or key creation has its own lifecycle. After an ambiguous response on those endpoints, inspect current state before repeating the operation. Handle incoming webhook duplication separately by storing the verified event ID.
KEEP BUILDING