Idempotency

Endpoints that create data can accept an Idempotency-Key header, so you can retry them after a timeout or 5xx without creating duplicates. An endpoint’s reference page says whether it supports the header. They include:

POST /resumes
POST /talent-network/candidates/submit
POST /talent-network/candidates/submit-bulk

curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/submit-bulk" \
  -H "Authorization: Bearer $PARAFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0f3c1e-8d2a-4a51-9a0e-3f7a2f6c9e14" \
  -d @batch.json

How it works

Generate a unique value, such as a UUID, for each logical request. Send the same value when you retry that request.
The first successful response is stored for 24 hours. A retry with the same key and the same body gets the stored response back, including the original batchId, instead of running the request again.
Keys are scoped to your API key and the endpoint, so the same value on a different endpoint or under a different key doesn’t collide.
If the first attempt fails with an error, nothing is stored, and a retry with the same key runs the request again.

Conflicts

These cases return 409 with error type idempotency_error:

Case	Message
Same key, different request body	`Idempotency-Key reused with a different request body`
Same key while the first attempt is still running	`A request with this Idempotency-Key is already in progress`

Wait and retry the in-progress case. Fix the body-mismatch case by sending a new key.

Endpoints that don’t need it

Endpoints that don’t support the header ignore it. Reads have no side effects, and some writes converge on the same state when retried, so they don’t need it. For example:

PUT /talent-network/candidates/{candidateUserId}/preferences and PUT …/fast-track set a value, so repeating them is harmless.
POST /talent-network/candidates/off-market and POST …/re-enable report already_off_market or already_on_market on a repeat.

Overview

Using the API

How it works

Conflicts

Endpoints that don’t need it

​How it works

​Conflicts

​Endpoints that don’t need it

How it works

Conflicts

Endpoints that don’t need it