One key for one intended operation
Idempotency means a retry can recover the same operation instead of creating another one. Give each intended screening or batch a key and save it with the request before calling the API.
POST screenings and POST batches require an Idempotency-Key of 8 to 128 URL-safe letters, digits, underscores, colons, periods, or hyphens. Reuse the key with the same normalized request to replay the accepted result or batch. A different request or operation using that key causes a conflict.
The key is scoped to the organization and environment. A new key means a new intended screening, even if the name is the same. Keep your customer reference separate from this operation key.
Persist operation intent before sending the network request
Create a client-side operation record containing a UUID idempotency key, endpoint, environment and the exact intended request. Save it before making the call. Mark it accepted only after you durably associate the response ID; retain an uncertain state after a timeout. Recovery reads this record and resends the same key and body.
The required idempotency header applies to screening and batch creation, monitor creation, monitor definition edits and monitor scheduling controls. Scope is organization plus environment, not the individual API key, so a replacement credential must still use the original operation key. Do not reuse a key for a different endpoint or subject.
Screening retries recover the retained original result; batch retries replay the acceptance, so use GET /batches/{id} for progress. Monitor-create retries also replay acceptance; use the current monitor resource for its status. Retention expiry can prevent result recovery even though the original operation was accepted.
There is no blanket idempotency guarantee for every POST. Upload-intent creation, webhook endpoint registration and optional case creation require endpoint-specific reconciliation after an uncertain response. Incoming webhooks use event-ID deduplication, not an Idempotency-Key supplied by your receiver.
Recover after an uncertain response
The server may save a screening before the connection fails. Retry with the original key and body so it can find that accepted operation. Do not create a new key just because the response was lost. Screening evidence, usage, and the receipt are committed together.
A new monitor-update receipt keeps the revision and status that were acknowledged. Some review changes instead return the current saved resource when they recognize an earlier action. The action is not repeated, but the response bytes are not guaranteed to be identical for every endpoint.
An idempotency receipt and retained evidence serve different purposes. If the evidence has expired, a full replay may no longer be possible. Save the result ID and retention policy with your operation. Minimal retention limits what can be recovered later.
Do not assume every endpoint shares this contract
Screening, batch and monitor acceptance, policy publication and intake use their documented idempotency contracts. Human review and governance mutations also require current revisions where specified. Inspect the endpoint contract before retrying an ambiguous response. Handle incoming webhook duplication separately by storing the verified event ID.
Frequently asked questions
When should I create a new Idempotency-Key?
Create it when you start a new intended operation, then save it with the exact request. Reuse it for retries of that same operation. A corrected subject, changed coverage, or different operation needs a new key; a lost response alone does not.
Can a replacement API key recover an earlier screening operation?
Yes, when it has the required access in the same organization and environment. Idempotency is not scoped to the individual credential. Keep the original operation key and body after replacing the API key so the request still identifies the same work.
Does every POST endpoint support the same retry behavior?
No. Screening, batch, and monitor operations have documented idempotency contracts. Upload-intent creation, webhook registration, and optional case creation require their own recovery checks after an uncertain response. Read the endpoint instructions before automatically repeating a POST.
Can idempotency replay evidence after its retention period ends?
Not necessarily. The operation receipt and retained evidence serve different purposes. An accepted operation may still be identifiable after the inputs needed for a full result are gone. Keep result IDs and retention settings, and retrieve evidence while it remains available.
KEEP BUILDING