Idempotency
An operation is idempotent when doing it twice has the same effect as doing it once, so a retry can't create a second contract or send a second email.
In plain words
Networks fail in an awkward way. Your code sends a request, the server does the work, and the reply gets lost. Your code doesn't know if it worked, so it tries again. Without idempotency, you now have two contracts and the signer has two emails.
The fix is a key. Your code attaches a unique key to the request. If the server sees the same key again, it returns the first result and does nothing new.
An example
A Clay table sends a contract for each row that reaches "Ready". A timeout makes Clay retry row 214. Both tries carry the key contract-row-214. The first creates and sends the document. The second gets back the same document ID, and the signer gets one email.
How it shows up in docuinked
Every docuinked call that writes takes an Idempotency-Key header of up to 200 characters. The same key returns the first result and doesn't repeat the work.
curl https://docuinked.com/v1/documents \
-H "Authorization: Bearer $DOCUINKED_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: contract-row-214" \
-d '{"title": "Services agreement", "pdf_url": "https://example.com/c.pdf",
"signers": [{"name": "Dana Reed", "email": "dana@example.com"}]}'Build the key from something stable in your own data, such as a record ID plus the document type. Don't use a random value per try, or every retry looks new.
This is why we say reruns must never send twice. It matters most in workflows, where tools retry on their own, and for agents, which may call a tool again if they lose track.
Common confusions
Idempotent is not the same as safe. A read is safe: it changes nothing. A write can be idempotent and still change things, once.
Keys are per action. Reuse a key only for a retry of the same request. A new contract for the same person needs a new key.
Receiving side too. A webhook may arrive twice. Your handler should ignore an event ID it has already handled.
Related terms
See the API reference and errors.
Common questions
What makes a good idempotency key?
A value that is the same on every retry of one action and different for every other action. A pattern like offer-<candidate id>-v1 works well.
What if I send the same key with a different body?
Treat that as a bug in your code. A key should always mean one exact request, so give a changed request a new key.
Do GET requests need an idempotency key?
No. Reads change nothing, so repeating them is already harmless.
Related
Try it in test mode
Free during the beta. Test keys send no email, so you can build the whole flow first.