Network requests fail. Retries are correct. Double-creates are not. For account creation, send an Idempotency-Key header. If you send the same key with the same body again, Zquence returns the account it already created instead of creating a second one.

​
Which endpoints support it?

EndpointHow retries are made safe
POST /v1/accountsIdempotency-Key header, required.
POST /v1/tenants/add-userNo header needed. The call is idempotent on email (and phone when sent).
POST /v1/sanctions/screenSend requestNonce in the body.
Other endpoints ignore the Idempotency-Key header.

​
How it works

1

Build a key from your business event

Use something that stays the same for every retry of the same operation, for example crm-case-10482-open. A UUID also works if you store it before the first attempt. Keys must be 8–255 visible ASCII characters with no spaces.
2

Send it as a header

Idempotency-Key: crm-case-10482-open
3

Retry with the same key and body

If the request times out or returns 429 or 5xx, send it again unchanged.

​
Behavior guarantees

  • Keys are scoped to the API key and its environment. The same string on a different key never collides.
  • Keys don’t expire. A key stays tied to the account it created.
  • A replay returns 201 Created with the account’s current state. No second account, emails, or webhooks.
  • Reusing a key with a different body returns 409 with code idempotency_key_reused.
  • Two bodies count as the same after trimming whitespace, lowercasing accountType, and ignoring participant order.
  • A request that fails validation (400) stores nothing, so you can fix the body and reuse the key.

​
Example

curl https://v2.app-dev.zquence.com/v1/accounts \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Idempotency-Key: crm-case-10482-open" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "permanent",
    "title": "Maria Alvarez onboarding",
    "externalReference": "crm-case-10482",
    "participants": [
      { "role": "customer", "userId": "6a25cdac36bc6230704b5b59" }
    ]
  }'

​
What to key on

ScenarioGood idempotency key
Opening an account for a CRM case"crm-case-" + caseId + "-open"
Opening an account for an order"order-" + orderId + "-open"
The key should come from the business event, so every retry of that event produces the same key. Pair it with externalReference for a second guarantee: even with a new key, Zquence rejects a second account for the same reference with 409 external_reference_exists.