Using the API

Idempotency

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

Last updated September 11, 2026

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 Create a lead
POST/v1/leads/create Create a standalone lead (deprecated)
POST/v1/campaigns Create a campaign
POST/v1/crm/deals 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:

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 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 or POST /v1/crm/deals creates a duplicate.