Idempotency

Network failures can leave you unsure whether a POST succeeded. To retry safely without creating duplicate records, send an Idempotency-Key header. GetRaze stores the result of the first request and replays it for any retry that uses the same key.

Idempotency is opt-in — requests without the header behave exactly as before.

Supported endpoints

Method	Endpoint
POST	/contacts
POST	/opportunities
POST	/campaigns/:id/contacts
POST	/instagram-agents/:id/profiles

How to use it

Generate a unique key per logical operation (a UUID v4 is ideal) and send it in the header:

curl --request POST \
  --url "https://app.getraze.com/external/v1/contacts" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 7f1c2e9a-3b4d-4a6e-9c1f-2d3e4f5a6b7c" \
  --data '{ "name": "Jane Smith", "email": "jane@company.com" }'

If the request times out, retry it with the same Idempotency-Key. The second call returns the original response (with an Idempotent-Replayed: true header) instead of creating a second contact.

Behaviour

Situation	Result
Same key, same body, first call	Runs normally; the 2xx response is stored
Same key, same body, retried	Replays the stored response (Idempotent-Replayed: true)
Same key, same body, original still in flight	409 IDEMPOTENCY_CONFLICT
Same key, different body	422 IDEMPOTENCY_KEY_REUSED
First call returned a non-2xx error	Not stored — the key is free to retry

Notes

• Keys are scoped to your account and stored for 24 hours. After that, the same key is treated as new.
• Only the body, method and path are fingerprinted — query parameters are not part of the key identity.
• The Idempotency-Key must be a string of 1–255 characters; otherwise the request returns 400 VALIDATION_ERROR.
• Non-2xx responses are intentionally not cached, so a transient failure can be retried with the same key.