Skip to main content

Extract and submit candidates

Adding candidates from CVs takes two calls. The first reads details out of the files and saves nothing. The second saves the candidates you chose.

Why two steps​

Reading a CV is a best guess. A parser can misread a name or miss an email. Adding a candidate is a commitment: a record is created, a workflow starts and an email may go out.

Splitting the calls puts a review between them. Your code, or a person in your own tool, can drop the rows that look wrong and fix the ones that are close, before anyone enters the pipeline or gets an email.

POST/candidates/extractPOST/candidates/submit
Creates recordsNoYes
Emails a candidateNoYes, when notify_candidate is true and the workflow has an invitation ready
TakesUp to 10 CV filesUp to 50 candidates
Safe to repeatYesYes, with an Idempotency-Key

Which jobs accept candidates​

Only an active job. Extract and submit both refuse any other job with 409 job_not_active before doing anything, so a paused or closed job costs you nothing. Find a job's status with List jobs.

Step 1: Extract​

Send the job ID and the files as multipart/form-data. Repeat the files field once per file. Files must be PDF, DOC or DOCX, up to 5 MB each.

Each file gets exactly one entry in extractions, in upload order, so index always matches the file you sent. A bad file never fails the whole request. It comes back with a status other than ok and a message saying why.

Extraction reads identity only: name, email and phone. It does not return skills, work history or a score. Those are produced later, by the job's workflow.

Extraction statuses​

statusMeaningWhat to do
okDetails read, no match in your workspace.Submit it.
duplicateDetails read. The email or phone matches an existing candidate.Read duplicates and decide.
needs_emailA CV was read but no email was found.Add an email yourself, or drop the row.
unreadableNo text could be read. Often a scanned image.Ask for a text-based CV.
unsupported_typeNot a PDF, DOC or DOCX file.Convert it and send it again.
too_largeOver 5 MB.Compress it and send it again.
failedSomething went wrong on our side.Send that file again.

Duplicates​

A duplicate means the person already exists somewhere in your workspace. They may be on a different job. Each entry in duplicates shows the existing candidate's ID and name, and whether the email or the phone matched:

{
"status": "duplicate",
"email": "vikram.shah@example.com",
"duplicates": [
{
"candidate_id": "66d3f9a2c8b1e7045a6d2c10",
"name": "Vikram Shah",
"matched_on": "email"
}
]
}

You never see the existing candidate's email or phone. A phone match would otherwise reveal someone else's email.

We do not decide for you. Submitting a duplicate is allowed. If the person already has an application on the same job, that row fails with already_applied instead.

The cv_id​

Every readable file is stored and referenced by a cv_id. You pass it to step 2 so the file is attached without uploading it again. A cv_id that is not submitted within 24 hours is deleted and stops working.

A cv_id attaches to one candidate only. If that candidate cannot be added, the cv_id is given back, so you can use it again.

Step 2: Submit​

Send the values you reviewed, not the raw extraction. If a person corrected a name or added a phone number, send the corrected value.

{
"job_id": "66f1c2a9b3d4e5f607182934",
"notify_candidate": true,
"candidates": [
{
"cv_id": "cv_7Qm2xN4vKdA9pR1sTe6WbZ",
"name": "Ananya Rao",
"email": "ananya.rao@example.com",
"phone": "+919812345678",
"external_id": "greenhouse-48213",
"metadata": { "source": "careers-page", "recruiter": "priya" }
}
]
}
  • email is the only required field per candidate. name defaults to the part of the email before the @.
  • external_id is your own ID for the person, such as an ATS record. It comes back in the response, and it is included in the webhook payload of every event about this candidate, so you can map results to your records.
  • metadata holds up to 20 string pairs. Keys use only letters, numbers, underscores and hyphens, up to 64 characters. Values are up to 500 characters. Tarkflo stores them on the application and sends them on those same webhook payloads.
  • notify_candidate defaults to true. Set it to false and no invitation email goes out automatically, including the one a CV screening step would otherwise release later. A recruiter can still send the invitation from the dashboard, and the invitation for a later round is sent as usual. When it is true, whether an email goes out also depends on the job's workflow.

Partial success​

Rows succeed or fail on their own. The response lists both, each with its index:

{
"created": [
{ "index": 0, "application_id": "66f2d4b8e1a7c3095b6f8a21", "name": "Ananya Rao", "email": "ananya.rao@example.com", "external_id": "greenhouse-48213" }
],
"failed": [
{ "index": 1, "email": "vikram.shah@example.com", "external_id": null, "reason": "already_applied", "message": "This candidate already has an application on this job." }
]
}

A 200 means at least one candidate was created, so always read failed. If nobody was created the response is 422 no_candidates_created.

reasonMeaningWhat to do
invalid_emailThe email is missing or malformed.Fix it and resend that row.
invalid_cvThe cv_id does not exist, has expired, was already used, or belongs to another workspace.Extract the file again.
already_appliedThis person already has an application on this job.Nothing. They are already there.
workflow_not_activeThe job's workflow is not active, so no one can enter it.Activate it in the dashboard.
failedSomething went wrong on our side.Resend that row.

Retrying safely​

Always send an Idempotency-Key. If the request times out and you do not know whether it landed, send it again with the same key and the same body. You get the original response, marked with an Idempotent-Replayed: true header, and nobody is added twice. Generate the key once per batch and store it with the batch. See Idempotency.

The whole flow​

This script extracts a folder of CVs, keeps the clean rows, and submits them. Put your own review step where the comment says so.

# Needs curl and jq. At most 10 files per extract call.
JOB_ID="66f1c2a9b3d4e5f607182934"

curl -s -X POST https://api.tarkflo.com/v1/candidates/extract \
-H "Authorization: Bearer $TARKFLO_API_KEY" \
-F "job_id=$JOB_ID" \
-F "files=@./ananya-rao.pdf" \
-F "files=@./vikram-shah.docx" \
| jq --arg job "$JOB_ID" '{
job_id: $job,
candidates: [.extractions[] | select(.status == "ok") | {cv_id, name, email, phone}]
}' \
| curl -X POST https://api.tarkflo.com/v1/candidates/submit \
-H "Authorization: Bearer $TARKFLO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @-