Platform
Idempotency
Retrying a request never creates a second lead.
Send an Idempotency-Key header with every POST /v1/leads — a UUID works well. Keys are scoped to your project and environment and may be up to 255 printable ASCII characters.
| Situation | Result |
|---|---|
| First request | 201 — the lead is created |
| Same key, same external_id | 200 with the original lead and Place-Idempotent-Replay: true |
| Same key, different external_id | 409 idempotency_key_reused |
| No key, external_id sent before | 200 replay — external_id is the natural key |
The same rules, with request examples, are in the Leads reference.
Reuse a key only to retry the same lead. After a 5xx or a timeout, retry with the same key and exponential backoff.