Idempotency

Prevent duplicate records when your integration retries POST or PATCH requests.

IntermediateownermanagerdeveloperUpdated 2026-03-19

Idempotency

All POST and PATCH requests to the external API require an Idempotency-Key header.

That includes every current public write endpoint:

  • /api/v1/leads
  • /api/v1/leads/:id
  • /api/v1/clients
  • /api/v1/clients/:id
  • /api/v1/estimates
  • /api/v1/estimates/:id
  • /api/v1/jobs
  • /api/v1/jobs/:id
  • /api/v1/invoices
  • /api/v1/invoices/:id
  • /api/v1/webhooks

This protects you from duplicate writes when a request times out, your worker retries, or a no-code platform like Zapier replays the same step.

How It Works

  1. Your integration sends a unique Idempotency-Key.
  2. CE Pro stores the request fingerprint and response.
  3. If you retry the same request with the same key and the same payload, CE Pro returns the original result instead of creating a duplicate record.
  4. If you reuse the same key with a different payload, CE Pro returns 409.
  5. If another request with the same key is still running, CE Pro returns 409 idempotency_in_progress.

Header Example

Idempotency-Key: cepro-lead-20260314-001

When To Reuse A Key

Reuse the same key only when you are retrying the exact same operation.

Examples:

  • A lead-create call timed out and you want to retry it safely
  • A network hop failed after the server already processed the request
  • A workflow runner retries the same step automatically

Create a new key for every new write operation.

Recommended Strategy

Use a key derived from your upstream system's stable id:

  • Form submission id
  • CRM record id
  • Queue message id
  • Workflow run id plus step id

That keeps retries safe even across worker restarts.

Error Behavior

  • Same key + same body: CE Pro replays the original response
  • Same key + different body: 409
  • Same key while the original request is still running: 409 idempotency_in_progress
  • Missing key on POST or PATCH: request rejected

CE Pro keeps completed and failed idempotency records for 72 hours, which is long enough to cover normal retry windows without storing them forever.

Practical Tip For No-Code Tools

If your tool supports a stable step identifier, map that into Idempotency-Key. If it does not, create a deterministic key from the external object id you are syncing.

Related articles

Was this article helpful?

Still need help? Contact support