Idempotency

curl "$FIRSTSALES_BASE_URL/api/v1/organizations/org_123/workspaces/ws_123/contacts" \
  -X POST \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-row-001" \
  -d '{"email":"alex@example.com"}'

firstsales contacts create \
  --org org_123 \
  --workspace ws_123 \
  --data '{"email":"alex@example.com"}' \
  --idempotency-key import-row-001

​

Rules

• Keys are stored per organization and Developer API key for 24 hours.
• The stored record covers the method, the route, and the request body.
• Reusing a key with the same method, route, and body returns the original response.
• Reusing a key with a different method, route, or body returns 409 idempotency_key_reused.
• Sending the key again while the first request is still running returns 409 idempotency_request_in_progress. Retry the same request after a short wait.
• Use deterministic keys for imports, approvals, and lifecycle actions.
• Do not use the same idempotency key across unrelated operations.

​

Routes that require a key

​

Replays and rate limits

• the request is a POST, PUT, PATCH, or DELETE under /api/v1;
• a completed record exists for the same organization, API key, and idempotency key;
• the method, the concrete route, and the body match that record.