Skip to main content
Network failures happen. Idempotency keys let you safely retry a POST request — for example after a timeout — without risk of creating a duplicate contact or firing an event twice.

​
How it works

Send an Idempotency-Key header with any POST request. The value can be any unique string, such as a UUID you generate per logical operation. 
curl --location --request POST 'https://api.audienceful.com/v2/people' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--header 'Idempotency-Key: 8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8' \
--data-raw '{ "email": "[email protected]" }'

import requests

url = "https://api.audienceful.com/v2/people"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
    "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
}
payload = {"email": "[email protected]"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.audienceful.com/v2/people", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
    "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
  },
  body: JSON.stringify({ email: "[email protected]" }),
});
const data = await response.json();
console.log(data);
  • The first request with a given key executes normally, and its response is stored for 24 hours.
  • A retry with the same key replays the stored response and adds an Idempotent-Replay: true header — the operation does not run a second time.
  • A retry sent while the original is still in flight returns a 409 with code idempotency_in_progress.
  • Server errors (5xx) are never cached, so a request that failed on our side can be safely retried with the same key.
Keys are scoped per workspace and per endpoint, so the same key value used against two different endpoints is treated as two independent operations.
Generate a fresh idempotency key for each distinct operation, and reuse that same key only when retrying that specific operation.