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/extract | POST/candidates/submit | |
|---|---|---|
| Creates records | No | Yes |
| Emails a candidate | No | Yes, when notify_candidate is true and the workflow has an invitation ready |
| Takes | Up to 10 CV files | Up to 50 candidates |
| Safe to repeat | Yes | Yes, 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
status | Meaning | What to do |
|---|---|---|
ok | Details read, no match in your workspace. | Submit it. |
duplicate | Details read. The email or phone matches an existing candidate. | Read duplicates and decide. |
needs_email | A CV was read but no email was found. | Add an email yourself, or drop the row. |
unreadable | No text could be read. Often a scanned image. | Ask for a text-based CV. |
unsupported_type | Not a PDF, DOC or DOCX file. | Convert it and send it again. |
too_large | Over 5 MB. | Compress it and send it again. |
failed | Something 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" }
}
]
}
emailis the only required field per candidate.namedefaults to the part of the email before the@.external_idis 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.metadataholds 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_candidatedefaults totrue. Set it tofalseand 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 istrue, 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.
reason | Meaning | What to do |
|---|---|---|
invalid_email | The email is missing or malformed. | Fix it and resend that row. |
invalid_cv | The cv_id does not exist, has expired, was already used, or belongs to another workspace. | Extract the file again. |
already_applied | This person already has an application on this job. | Nothing. They are already there. |
workflow_not_active | The job's workflow is not active, so no one can enter it. | Activate it in the dashboard. |
failed | Something 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.
- cURL
- Node.js
- Python
# 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 @-
// Node.js 20 or later. Run: node import.mjs ./cv1.pdf ./cv2.docx
import { openAsBlob } from "node:fs";
import { randomUUID } from "node:crypto";
const API = "https://api.tarkflo.com/v1";
const JOB_ID = "66f1c2a9b3d4e5f607182934";
const auth = { Authorization: `Bearer ${process.env.TARKFLO_API_KEY}` };
async function call(path, init) {
const res = await fetch(`${API}${path}`, { ...init, headers: { ...auth, ...init.headers } });
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error}: ${body.message}`);
return body;
}
// Step 1: extract. At most 10 files per call.
const form = new FormData();
form.append("job_id", JOB_ID);
for (const path of process.argv.slice(2, 12)) {
form.append("files", await openAsBlob(path), path.split("/").pop());
}
const { extractions } = await call("/candidates/extract", { method: "POST", body: form });
// Review: keep only clean rows. Replace this with your own checks or a human review.
const keep = extractions.filter((x) => x.status === "ok");
for (const x of extractions.filter((x) => x.status !== "ok")) {
console.warn(`Skipped ${x.filename}: ${x.status}. ${x.message ?? ""}`);
}
if (keep.length === 0) process.exit(0);
// Step 2: submit.
const { created, failed } = await call("/candidates/submit", {
method: "POST",
headers: { "Idempotency-Key": randomUUID(), "Content-Type": "application/json" },
body: JSON.stringify({
job_id: JOB_ID,
candidates: keep.map(({ cv_id, name, email, phone }) => ({ cv_id, name, email, phone })),
}),
});
console.log(`${created.length} added, ${failed.length} failed`, failed);
# Python 3.9 or later, pip install requests. Run: python import_cvs.py cv1.pdf cv2.docx
import os
import sys
import uuid
import requests
API = "https://api.tarkflo.com/v1"
JOB_ID = "66f1c2a9b3d4e5f607182934"
AUTH = {"Authorization": f"Bearer {os.environ['TARKFLO_API_KEY']}"}
def call(method, path, **kwargs):
headers = {**AUTH, **kwargs.pop("headers", {})}
res = requests.request(method, f"{API}{path}", headers=headers, timeout=120, **kwargs)
body = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {body['error']}: {body['message']}")
return body
# Step 1: extract. At most 10 files per call.
paths = sys.argv[1:11]
files = [("files", (os.path.basename(p), open(p, "rb"))) for p in paths]
extractions = call("POST", "/candidates/extract", data={"job_id": JOB_ID}, files=files)["extractions"]
# Review: keep only clean rows. Replace this with your own checks or a human review.
keep = [x for x in extractions if x["status"] == "ok"]
for x in extractions:
if x["status"] != "ok":
print(f"Skipped {x['filename']}: {x['status']}. {x['message'] or ''}")
if not keep:
sys.exit(0)
# Step 2: submit.
result = call(
"POST",
"/candidates/submit",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": JOB_ID,
"candidates": [
{k: x[k] for k in ("cv_id", "name", "email", "phone")} for x in keep
],
},
)
print(f"{len(result['created'])} added, {len(result['failed'])} failed", result["failed"])