Skip to main content

Quickstart

Add a candidate to a job in five steps. You need a Tarkflo workspace with an active job and one CV file (PDF, DOC or DOCX).

Node.js examples need Node.js 20 or later and no packages. Save them as .mjs files. Python examples need pip install requests.

1. Create an API key​

In Tarkflo, open Settings, API keys and choose Create API key. Give it a name, choose the role it acts as (it needs to read jobs and add candidates, which the Recruiter role does), and choose when it expires. Copy the key when it appears. It is shown once.

Keep it out of your code and out of git. Put it in an environment variable:

export TARKFLO_API_KEY="tf_live_paste_your_key_here"
note

At first only the Owner can create keys. Authentication explains how to give that permission to other people.

2. Find your job ID​

Candidates are submitted to a job, so you need its ID. List your jobs and copy the id of an active one.

curl "https://api.tarkflo.com/v1/jobs?status=active" \
-H "Authorization: Bearer $TARKFLO_API_KEY"
200 OK
{
"data": [
{
"id": "66f1c2a9b3d4e5f607182934",
"title": "Senior Backend Engineer",
"status": "active",
"workflow": { "id": "66e8a01c5b7d2f3a90c4d1e2", "name": "Engineering, two rounds" },
"created_at": "2026-09-18T09:41:12.000Z"
}
],
"has_more": false,
"next_cursor": null
}

3. Extract the details​

Send the CV with the job ID. Tarkflo reads the name, email and phone and hands them back. Nothing is added to the pipeline yet.

curl -X POST https://api.tarkflo.com/v1/candidates/extract \
-H "Authorization: Bearer $TARKFLO_API_KEY" \
-F "job_id=66f1c2a9b3d4e5f607182934" \
-F "files=@./ananya-rao.pdf"
200 OK
{
"extractions": [
{
"index": 0,
"filename": "ananya-rao.pdf",
"status": "ok",
"cv_id": "cv_7Qm2xN4vKdA9pR1sTe6WbZ",
"name": "Ananya Rao",
"email": "ananya.rao@example.com",
"phone": "+919812345678",
"message": null,
"duplicates": []
}
]
}

4. Review what came back​

Reading a CV is a best guess, so look before you submit. Each entry has a status:

  • ok: the details were read and no one in your workspace matches. Safe to submit.
  • duplicate: the email or phone matches an existing candidate. Look at duplicates and decide.
  • needs_email: no email was found. Add one before you submit.
  • Anything else means the file could not be used. Read message.

The full list of statuses says what to do for each one.

5. Submit the candidate​

Send the values you reviewed, with the cv_id from step 3. Add external_id to carry your own record ID through, and an Idempotency-Key so a retry never adds the same person twice.

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 '{
"job_id": "66f1c2a9b3d4e5f607182934",
"candidates": [
{
"cv_id": "cv_7Qm2xN4vKdA9pR1sTe6WbZ",
"name": "Ananya Rao",
"email": "ananya.rao@example.com",
"phone": "+919812345678",
"external_id": "greenhouse-48213"
}
]
}'
200 OK
{
"created": [
{
"index": 0,
"application_id": "66f2d4b8e1a7c3095b6f8a21",
"name": "Ananya Rao",
"email": "ananya.rao@example.com",
"external_id": "greenhouse-48213"
}
],
"failed": []
}

Open the job in Tarkflo. The candidate is in the pipeline, and the workflow has started.

If something fails​

StatusCodeWhat to do
401invalid_api_keyThe key is missing, mistyped, expired or revoked. Create a new one.
403forbiddenThe role the key acts as lacks the permission this call needs. The response names it in required.
404job_not_foundThe job ID is wrong, or this key cannot see that job.
413too_many_filesMore than 10 CVs in one extract call. Split them.
429rate_limitedWait for the Retry-After header, then retry.

Every error has the same shape. See Errors.