Idempotency

Networks fail. If a request to invite a candidate times out, you cannot know whether Heizen received it. Send an Idempotency-Key header and you can retry without inviting them twice.

curl https://api.interviewer.heizen.tech/api/v1/invitations \
  -H "Authorization: Bearer $HEIZEN_API_KEY" \
  -H "Idempotency-Key: application-981-invite" \
  -H "Content-Type: application/json" \
  -d '{ "interviewer_id": "int_…", "candidate": { "email": "ada@example.com", "name": "Ada Lovelace" } }'

How it works

• The key is any string up to 255 characters. A value tied to your own record, such as an application id, works well. A random UUID also works.
• The first successful response is stored for 24 hours. Repeating the same request with the same key returns that response with Idempotent-Replayed: true and does nothing else.
• Keys are scoped to your organisation. The stored request includes the mode, so replaying a test request with a live key counts as a different request.
• If the first request fails, Heizen forgets the key, so a retry runs for real.
• Reusing a key with a different body gets 409 idempotency_key_reused.
• Sending the same key while the first request is still running gets 409 idempotency_key_in_use. Wait a moment and retry.

Which endpoints

Idempotency applies to these POST endpoints:

• POST /v1/candidates and POST /v1/candidates/import
• POST /v1/invitations, /invitations/bulk, and /invitations/{id}/resend, /extend, /cancel
• POST /v1/exports
• POST /v1/webhook_endpoints

GET, PATCH and DELETE requests are naturally safe to repeat, and the header is ignored on them.