Skip to main content
A connection drops mid-request and the client cannot tell whether it arrived. An unguarded retry creates a second load or a second document. The Idempotency-Key header solves that: the server remembers the key and answers a repeat the same way it answered the first request, without creating anything again.

​
Where it works today

POST /files, POST /documents/{id}/_send, and the other writing endpoints do not accept the header. Repeating _send or a participant action returns a state error rather than creating a duplicate, so creation is the only dangerous retry — see “Living without idempotency” below.

​
Creating a document

Send Idempotency-Key with POST /documents and a repeat of the same request returns the same document instead of a second one.
A key lives 24 hours and belongs to your API key, so two API keys may use the same string without colliding. The key is claimed before the document is created, which is what stops two simultaneous requests with one key from producing two documents — the double-submit case. A repeat is not served from a cache: the server re-reads the document through the normal path, so permissions are checked on every reply and the data is current.

​
Ingest

You choose the key and send it as a header. It must be unique per batch content: the same batch keeps its key, a new batch gets a new one.
The 409 is not a bug in your logic; it confirms the first attempt landed. Treat it as success and do not resend the batch.
A good key is deterministic and derived from the data: employees-2026-02-10-001, persons-<batch hash>. A random UUID generated on every attempt protects nothing, because the retry carries a new one.

​
Living without idempotency

Use Idempotency-Key for document creation. For the other writes, lower the risk like this:
1

Record your own identifier before the call

Store the intent (“create an order for employee X from template Y”) together with your own operation key, and only then call the API.
2

After a drop, do not retry blindly

First check whether the document already exists: GET /documents?type_id=…&created_after=…&search=…. If it does, store its id and skip the retry.
3

Retry reads and explicitly safe actions only

GET requests are free to repeat. Repeating _approve or _sign on a slot that already acted returns a state error rather than creating a duplicate.
The document list and its filters are described in Listing documents.