Loading page
Skip to content

Tarkflo / Developers

AI interview API.
Your pipeline. Our engine.

The Tarkflo API connects AI interviews to your own ATS or hiring platform. Create a candidate’s interview link, follow its status and retrieve the result. Your system stays in charge.

  • REST / JSON
  • Signed webhooks
  • MCP

Connected by design Illustrative network artwork

01 / Interview as a Service

One request.
An interview your system can work with.

Start with an active Tarkflo job whose workflow opens with an AI interview round. Send the job ID and candidate details from your server. Tarkflo runs the conversation on its interview page—not in your application.

Keep the returned interview link securely: it is shown once. If you lose it, the relink endpoint creates a new link and invalidates the old one.

Explore the interview guide (opens in a new tab)
Request / response
POST/v1/interviews
curl https://api.tarkflo.com/v1/interviews \
  -H "Authorization: Bearer $TARKFLO_API_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "YOUR_JOB_ID",
    "email": "ananya.rao@example.com"
  }'
200the candidate’s interview link
{
  "status": "ready",
  "interview_url": "https://hire.tarkflo.com/?token=…"
}

Example only: replace YOUR_JOB_ID. Use a unique idempotency key per operation and reuse it on retries. Keep your API key on the server. The response link is illustrative.

01

Create the interview

Send a job ID and a candidate. Keep the interview link returned by this call: it is shown only once.

02

Let the candidate speak

The candidate opens the link in their browser and talks with the AI interviewer. Your server does not drive the conversation.

03

Follow the status

Read interview status from your server. Use the status in your own pipeline, or connect hiring events through webhooks.

04

Read the result

When the interview completes, read its score, evaluation summary and scoped report link. Your team keeps the hiring decision.

02 / Candidate sync

Read first. Review.
Then write to the pipeline.

CV extraction and candidate submission are separate calls. Your integration decides which reviewed details become a candidate record.

01 / POST /v1/candidates/extract

Extract before you commit.

Read names, email addresses and phone numbers from CVs, with possible existing-candidate matches. Extraction does not create a candidate or send an invitation.

02 / POST /v1/candidates/submit

Submit what you reviewed.

Submit the reviewed details into a job’s pipeline and start its configured workflow. Carry your own external IDs and metadata, and use an idempotency key for retry-safe submission.

Extract → submit
01POST/v1/candidates/extract
{ "status": "ok", "name": "Ananya Rao",
  "email": "ananya.rao@example.com",
  "cv_id": "cv_7Qm2xN4v…" }
02POST/v1/candidates/submit
{ "application_id": "66f2d4b8…",
  "name": "Ananya Rao",
  "external_id": "greenhouse-48213" }

Illustrative response excerpts, not complete request bodies. Extraction creates no candidate; submission starts the job’s configured workflow.

03 / Clear boundaries

Operate through the API.
Configure in the dashboard.

The API refers to jobs, workflows and templates by ID. Configure those linked settings in the dashboard, where your team can review the checks and scoring criteria together.

With the API

  • Create interviews and retrieve their status and results
  • Extract candidate details from CVs, then submit reviewed candidates
  • Read jobs, descriptions and application counts
  • Read workflows, interview rounds and templates
  • Carry external IDs and metadata into candidate records

In the Tarkflo dashboard

  • Create and edit jobs
  • Build workflows, interview templates and scoring rubrics
  • Run, watch and review interviews
  • Manage billing, members, single sign-on and API keys

The API creates the candidate’s link and returns interview results. It does not drive the interview conversation or expose its questions and scoring rubric.

04 / Access & integration

Connect with control.

Create keys in the Tarkflo dashboard, with the role and permissions your integration needs. Owners can manage access and grant it to another role.

Server-side credentials. Role-based access.

API key controls

  • API keys use the role and permissions you assign
  • Set an expiry date or revoke a key when access is no longer needed
  • The key secret is shown only when you create it
  • API calls are attributed to the key in the audit log
  • Keep keys on your server, never in candidate-facing browser code

Events, not constant guesswork.

Connect hiring events to your own endpoint through outbound webhooks. Verify the Tarkflo-Signature header against the raw request body with HMAC-SHA256.

Tarkflo eventYour endpoint
Tarkflo-Signature: sha256=<hex>

Connect your AI tools with MCP.

The stateless MCP server exposes supported operations with the same API key permissions. Read jobs and workflows, submit candidates, and create or check interviews from a compatible tool.

POST https://api.tarkflo.com/mcp

Your next integration starts here

Start with your first interview.

Create an API key, configure a job in the dashboard and follow the quickstart. Keep your pipeline. Add the interview engine.

REST API · Signed webhooks · MCP