Idempotency

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.

Every response to a create call carries Idempotency-Replayed, reading true when you were served the stored response and false when the work actually ran. Branch on the value, not on whether the header is there.

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, so you never have to worry about colliding with anyone else's.

Keys are remembered for 24 hours

A key and its stored response live for 24 hours, then expire. That is sized for the thing this protects against, a retry seconds or minutes after a failed call, and it has one consequence worth knowing: reusing the same key a day later is not a replay, it is a new verification.

If you retry a genuinely stale operation, that is usually what you want, since a verification from yesterday has almost certainly expired anyway. What you should not do is treat the key as a permanent uniqueness constraint on your side. Deduplicate against your own records for that, and use the key for what it is good at, which is collapsing the burst of retries around one network failure.

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.