Idempotency
Safely retry a create call without producing a second verification
Network calls fail in the one way that matters most: the request arrives, the response does not. If
you retry blindly, you have created two verifications for one user. Idempotency-Key removes that
whole class of bug.
How it works
Send an Idempotency-Key header when you create a verification. POST /v1/verifications is the one
endpoint that honours it today. The first call runs normally and its response is stored against that
key. A later call with the same key and the same body replays the stored response instead of doing
the work again, and carries an Idempotency-Replayed: true header so you can tell the two apart.
Every other endpoint accepts the header and ignores it, so leaving it on a shared HTTP client is harmless, but only creation is protected. If that ever widens, it widens additively and the keys you already send keep working.
curl https://api.trustwix.com/v1/verifications \
-H "Authorization: Bearer TWK_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: kyc-user-123-2026-07-26" \
-d '{ "flow": "flw_id_and_liveness", "applicant": { "reference_id": "user-123" } }'Choosing a key
The key should be derived from what you are trying to do, not randomly generated, otherwise a retry
generates a new key and defeats the point. Something like kyc-{userId}-{attempt} works well: stable
across retries of one logical operation, distinct across genuinely separate operations. Keys are
scoped to your account and are up to 255 characters.
Same key, different body
Reusing a key with a different body is an error, not a silent overwrite. You get 409 with
type of idempotency_error. This is a guardrail: it means a key collision in your code surfaces
loudly instead of quietly returning the wrong user's verification.
If you legitimately want a different verification, use a different key.
What it does not do
Idempotency protects against duplicate submission on create. It does not make a failed request succeed, it does not extend to reads, which are naturally safe to repeat anyway, and it is not yet wired into the remaining mutating endpoints.
Use it on every create
There is no downside. Sending a key costs one header and eliminates the most expensive kind of duplicate you can create, a second verification against a real person.