Tarkflo Developer Handbook
Everything you need to connect, build, and hire with Tarkflo.
Featured articles
A good place to startQuickstart
Make your first API call and add a candidate in about ten minutes.
Authentication
Create API keys and securely connect your workspace.
API reference
Explore every endpoint, request field, and response.
Extract & submit
Turn CVs into candidates with a simple two-step flow.
Interview as a Service
Run Tarkflo interviews from your own ATS or application.
MCP server
Connect your AI tools to Tarkflo with the Model Context Protocol.
Integration guides
Keep buildinghttps://api.tarkflo.com/v1Explore the API overviewThe core flow, code examples, and what you can build.
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.
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
- Node.js
- Python
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"
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());
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())
{
"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": []
}
]
}
Or let Tarkflo run the interview
Have your own ATS and only want Tarkflo to run the interview? Create an interview instead
of Submit candidates: give it a candidate and a job, get back a link the candidate opens to interview on Tarkflo.
Poll Get an interview for status, then read Get an interview's report
once it is completed: a score, a verdict and a scoped link to the full report. See
Interview as a Service for the whole flow.
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, or create a single interview and get a link back | 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 can create that link (Create an interview) and read status and a result back, but it never drives the interview itself, and never sees its questions or rubric.
Where to go next
- Quickstart: add your first candidate in about ten minutes.
- Authentication: how keys work, what a key can do, and who can manage them.
- Extract and submit candidates: the two-step flow in depth, with duplicate handling and a full script.
- Interview as a Service: let Tarkflo run the interview for a candidate from your own ATS, link to result.
- Read jobs, workflows and templates: your hiring data as separate resources, from a job to its workflow to the interview template each round runs.
- API reference: every endpoint, field and error.