# Idempotency

Send an Idempotency-Key header so a retried create request returns the original result instead of doing the work twice.

A request that times out looks the same whether it failed or succeeded and lost its response. Retrying a create request blindly can then make a second campaign or deal. An `Idempotency-Key` header makes the retry safe: the API recognizes the repeat and returns the original response instead of doing the work again.

## Endpoints that accept a key

- [`POST /v1/leads`](https://docs.versionseven.ai/api-reference/leads/create-lead) Create a lead
- [`POST /v1/leads/create`](https://docs.versionseven.ai/api-reference/leads/create-standalone-lead) Create a standalone lead (deprecated)
- [`POST /v1/campaigns`](https://docs.versionseven.ai/api-reference/campaigns/create-campaign) Create a campaign
- [`POST /v1/crm/deals`](https://docs.versionseven.ai/api-reference/crm-deals/create-deal) Create a deal

The header is optional, and only these endpoints use it.

## Sending a key

Send any unique string of up to 255 characters. A UUID is ideal:

```bash
curl -X POST https://api.versionseven.ai/v1/crm/deals \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8e0c6d2f-3f7a-4d6e-9b1a-5c2e7f4a9d10" \
  -d '{"name": "Acme Corp expansion"}'
```

Create the key once for each operation, and send the same key with every retry of that operation. Keys are scoped to your organization and remembered for at least 24 hours.

## What a repeat returns

| Situation | Response |
| - | - |
| First request with the key | Runs normally. |
| Same key, same request | The original status and body, with the header `Idempotent-Replay: true`. The work isn't done again. |
| Same key, different request body | `409 IDEMPOTENCY_KEY_REUSED` |
| Same key while the first request is still running | `409 IDEMPOTENCY_IN_PROGRESS`, with `Retry-After` |
| The first request failed with a `5xx` error | The key isn't used up, so the retry runs normally. |

A replay returns the original response even when it was a `4xx` error. To send a corrected request, use a new key.

## Choosing keys

- Use a new key for each distinct operation, and the same key for every retry of it.
- To make a repeated sync safe, derive the key from your own record, such as your CRM's ID for the deal. Running the same sync twice then can't create the deal twice.
- Don't reuse a key for a different request. That answers `409 IDEMPOTENCY_KEY_REUSED`.

## Without a key

Leave the header out and nothing changes, but retries aren't protected. A retried [`POST /v1/leads`](https://docs.versionseven.ai/api-reference/leads/create-lead) answers `409 LEAD_ALREADY_IN_CAMPAIGN` if the first attempt went through (or `409 LEAD_ALREADY_EXISTS` when it had no `campaign_id`), while a retried [`POST /v1/campaigns`](https://docs.versionseven.ai/api-reference/campaigns/create-campaign) or [`POST /v1/crm/deals`](https://docs.versionseven.ai/api-reference/crm-deals/create-deal) creates a duplicate.