Submit candidates
POST/candidates/submit
Step 2 of 2. Save reviewed candidates into a job's pipeline. This is the call that creates records.
For each candidate, Tarkflo creates the candidate and an application on the job, attaches the CV when you pass
its cv_id, and starts the job's workflow. When notify_candidate is true and the workflow has an invitation
ready, the candidate is emailed. Whether an email actually goes out also depends on the job's workflow and your
remaining interview minutes.
Send the values you reviewed, not the raw extraction. If a person fixed a name or phone number, send the fixed value.
Send an Idempotency-Key header with every call. If your request times out and you retry with the same key and
body, you get the original response, marked with an Idempotent-Replayed: true header, and no one is added
twice. Keys are remembered for 24 hours.
Up to 50 candidates per request. Rows succeed or fail independently: the response lists what was
created and what failed, each with its index. If no row is created at all, the response is 422.
The role this key acts as needs the candidates:create permission.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 413
- 422
- 429
At least one candidate was created. Check failed for the rest.
Response Headers
Requests allowed in the current window for this key.
Requests left in the current window.
The request is malformed, or a field failed validation.
The key is missing, malformed, expired or revoked.
The key is valid but may not do this: the role it acts as lacks the permission this call needs (forbidden,
with the permission in required), or the workspace's plan has lapsed (billing_past_due: reads still work,
adding candidates is paused) or is suspended (account_suspended).
The job does not exist, or this key cannot see it.
Either the job is not active (job_not_active), or a request with this Idempotency-Key is still
running (request_in_progress). In the second case, wait a moment and retry with the same key.
More than 50 candidates in one request.
No candidate was created. Either every row failed, or the Idempotency-Key was already used with a
different body.
Too many requests. Wait for Retry-After seconds, then retry.
Response Headers
Seconds to wait before retrying.