Idempotency

The two send endpoints, from a template and from an uploaded PDF, require an Idempotency-Key header: any unique value you choose, 1 to 255 printable ASCII characters. If a request times out, retry it with the same key and you get the first result rather than a second document.

A replayed response carries Idempotent-Replayed: true, including a replayed error.
5xx and 429 outcomes are not stored, so the same key can retry them.
Keys are unique per workspace and endpoint, shared across that workspace's API keys, and kept for 24 hours.
The same key with a different body returns idempotency_key_reused.
Other endpoints refuse the header with idempotency_not_supported.

Choosing a key

Build the key from the record you are sending for, such as crm-8841-send-1 for the first contract on deal 8841, and save it with that record. A random value made fresh on each attempt defeats the point, because a retry would carry a new key and could send a second document.

Use a new key only when you mean a new document: after fixing a refused request, or when you deliberately send the same record again, such as crm-8841-send-2.

Retrying a send

Retry a timeout, a dropped connection, a 429, or a 5xx with the same key and the same body, waiting as long as Retry-After says. Do not retry other 4xx errors: the request itself needs fixing.

Send with retries

# --retry repeats the request after a timeout, 429, 500, 502, 503, or 504, waiting as Retry-After says,
# and sends the same Idempotency-Key each time.
curl --retry 5 -X POST "https://www.inkly.so/api/v1/documents" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  --data @send.json