1. Guides
CVViZ API Documentation
  • Start here
    • Quickstart
    • Authentication & permissions
  • Guides
    • API concepts
    • Create a job
    • Find candidates and download resumes
    • Pagination & filtering
    • Rate limits & usage
    • Errors & troubleshooting
    • Safe retries & idempotency
  • Jobs
    • Create a job
      POST
    • List jobs
      GET
    • Get a job
      GET
    • Update a job
      PATCH
    • List candidates for a job
      GET
    • List job benchmark resumes
      GET
    • List candidate job offers
      GET
    • Update a candidate application stage
      PATCH
    • Update job status
      PATCH
  • Candidates
    • List candidates
      GET
    • Get a candidate
      GET
    • Update a candidate
      PATCH
    • List applications for a candidate
      GET
    • List candidate events
      GET
    • List candidate documents
      GET
    • Download a candidate resume
      GET
  • Tasks
    • List tasks
    • Create a task
    • Update a task
    • Update task completion
  • Notes & tags
    • List job notes
    • Add a job note
    • List tags for a job
    • Add tags to a job
    • List tags for a candidate
    • Add tags to a candidate
    • List candidate notes
    • Add a candidate note
    • List candidate tags
  • Screening & interviews
    • List job pre-screening questions
    • List candidate screening answers
    • List candidate interview feedback
  • Organization & lookup data
    • List candidate stages for a job
    • Get job creation options
    • List industries
    • List job functions
    • List employer types
    • List client companies
    • List account users
    • List departments
    • List hiring managers
    • List candidate grades
  1. Guides

Safe retries & idempotency

An idempotency key lets you retry a write without applying the same operation twice.

Idempotent writes#

Every durable POST and PATCH customer API mutation requires an
Idempotency-Key header. Use a new opaque value of 8 to 128 characters for
each logical mutation. Retrying the same operation with the same key and body
returns the original result. Reusing the key with different content returns
409 Conflict.
Resume downloads and ordinary read requests do not require an idempotency
key. Upload-plan endpoints are not currently published.
CVViZ stores only a SHA-256 request fingerprint and a bounded public response
receipt for replay protection. Authorization headers and credential secrets
are never stored in mutation receipts.

Example header#

Generate your own unique value for each logical operation. Do not reuse this
documentation example across unrelated requests.

If a request times out#

1.
Keep the original method, URL, body and idempotency key.
2.
Retry with bounded exponential backoff and jitter.
3.
For 429 or 503, respect Retry-After when supplied.
4.
If you receive 409, read the details. Do not generate a new key merely
to work around a conflict; that can create a second operation.
A successful creation replay returns the original creation result, not a fresh
view of the job. Read the job to obtain its current state. To change a draft
to active later, use the status endpoint with a new key.

Reads and usage#

GET requests do not need an idempotency key. Retry transient failures with a
bounded backoff; do not repeatedly retry 400, 401 or 403 without
correcting the cause. Each admitted retry still counts toward metered usage,
even if its write result is replayed.
Previous
Errors & troubleshooting
Next
Create a job
Built with