Tarkflo API

Add candidates to a Tarkflo job from your own system. Send CVs, check what Tarkflo read from them, then save the ones you want into the pipeline. The job's workflow takes it from there.

Base URL

https://api.tarkflo.com/v1

Two calls do the work

POST/candidates/extract

Upload up to 10 CVs for a job. You get back each candidate's name, email and phone. Nothing is saved, so you can look before you commit.

POST/candidates/submit

Send the details you reviewed. Each candidate enters the job's pipeline, their CV is attached, and the job's workflow starts.

Here is the first call, with the response you get back:

cURL

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"

Node.js

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("job_id", "66f1c2a9b3d4e5f607182934");
form.append("files", await openAsBlob("./ananya-rao.pdf"), "ananya-rao.pdf");

const res = await fetch("https://api.tarkflo.com/v1/candidates/extract", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TARKFLO_API_KEY}` },
  body: form,
});
console.log(await res.json());

Python

import os
import requests

with open("ananya-rao.pdf", "rb") as cv:
    res = requests.post(
        "https://api.tarkflo.com/v1/candidates/extract",
        headers={"Authorization": f"Bearer {os.environ['TARKFLO_API_KEY']}"},
        data={"job_id": "66f1c2a9b3d4e5f607182934"},
        files=[("files", ("ananya-rao.pdf", cv))],
        timeout=120,
    )
print(res.json())

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": []
    }
  ]
}

What the API covers

You can, with the API	You do in the Tarkflo dashboard
List the jobs a key can see	Create and edit jobs
Read name, email and phone out of CVs	Build workflows, interview templates and scoring rubrics
Submit candidates into a job's pipeline	Run, watch and review interviews
Tag each candidate with your own ID and metadata	Manage billing, members, SSO, branding and API keys

The API refers to workflows and templates by ID. It never creates or edits them. That is a choice, not a gap. A workflow is a set of linked settings: stages, pass marks, interview templates, integrity rules. One API call cannot show you the checks the dashboard applies, so that stays where the checks are.

Interviews run through the candidate's own link, in their own browser. The API cannot start an interview on a candidate's behalf.

Where to go next

• Quickstart: add your first candidate in about ten minutes.
• Authentication: API users, keys, scopes and who can manage them.
• Extract and submit candidates: the two-step flow in depth, with duplicate handling and a full script.
• API reference: every endpoint, field and error.