Core concepts

Idempotency

Envelope creation accepts an idempotency key so a retried request cannot send the same document twice.

On this page

How it works
The header
Example
Where it applies

How it works

The two envelope-creation endpoints accept an optional X-Idempotency-Key header. Replaying a request with the same key, same API key, and an identical body returns the original response instead of creating a second envelope. A same-key request with a different body is treated as a new request.

Same key, different body

A repeat of the same key with a different body is treated as a new request, not a conflict — it will create a second envelope. Generate a fresh key per logical send (a UUID per row, per job, per user action) rather than reusing one across sends.

The header

Name	In	Type	Required	Description
`X-Idempotency-Key`	header	string	Optional	Client-generated key that makes creation safe to retry. Replaying the same key with an identical body returns the original response instead of creating a second envelope.Example: 0f6c1e5a-9b2d-4c7e-8a31-5f9d2b7c4e10

Example

Send the header alongside the usual API key. If the request times out on your side, replay it byte-for-byte with the same key — you will get the original response back rather than a duplicate envelope.

curl

curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/from-template/tpl_abc123" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Idempotency-Key: 0f6c1e5a-9b2d-4c7e-8a31-5f9d2b7c4e10" \
  -H "Content-Type: application/json" \
  -d '{
  "signers": [
    { "signerIndex": 1, "name": "Priya Sharma", "email": "priya.sharma@example.com" }
  ],
  "emailSubject": "Mutual NDA — Acme / Example"
}'

Where it applies

Only the two envelope-creation endpoints accept the header; everywhere else it is ignored. Reads are safe to repeat, and void, pause and resume settle on the same state whether you call them once or twice.

Resend is not safe to repeat

POST /envelopes/{id}/resend emails every pending signer each time you call it. Calling it twice sends two invitations. It does not accept an idempotency key, so guard against double-calls on your side.

For retry guidance on failures, see Errors and Rate limits.