Idempotency

A request can succeed on the server while its response is lost on the way back. Retrying it must not send the same applicant twice, create a second job or client, or spend sourcing credits again, so the operations that do these accept an Idempotency-Key header: applicant intake (alongside its own duplicate check on externalApplicationId), creating a job, creating a client and starting sourcing.

  • Make up a unique key for each request, such as a UUID, and send the same key on every retry of that request.
  • A retry after the request succeeded returns the first response, marked Idempotent-Replayed: true, without doing the work again.
  • A retry while the first attempt is still running is 409 idempotency_in_progress. Wait a moment and retry.
  • Reusing a key on the same operation for a different request, with another path or body, is 422 idempotency_key_reused.
  • Only successes are kept, for 24 hours. After an error, a retry with the same key runs again.
POST /v1/integration/applications
Idempotency-Key: 3f0c1d8e-6b6a-4f7e-9a51-0d2c5e7b9f10

The reference lists the header on each operation that accepts it.