Create an interview
POST/interviews
Interview as a Service: give Tarkflo one candidate and a job, get back a link the candidate opens to interview on Tarkflo. Use this instead of Submit candidates when your own system runs the pipeline and you only want Tarkflo to run the interview and hand back a result.
The job's workflow must open with an AI interview round — that is what makes it job_id ready for this
call. Build one in the dashboard once (questions, rubric, scoring), then create interviews against it for
as many candidates as you like. A job whose pipeline opens some other way, such as a CV screen or an
outreach step, gets 409 job_not_interview_ready; use Submit candidates for that
job instead.
The response carries interview_url. It is shown once, here. Tarkflo stores only a hash of the token
inside it, the same way an API key's own secret works, so it cannot be read back later. If you lose it
before handing it to the candidate, call Get a fresh interview link.
Tarkflo never emails the candidate here. Your own system owns that: send the link however you already
reach candidates. Set notify_candidate on Submit candidates if you want Tarkflo's
own invitation email instead.
Send an Idempotency-Key header, the same rules as Submit candidates: a retry with the same key and body
gets the original response back, marked Idempotent-Replayed: true, and creates nothing twice.
The role this key acts as needs the candidates:create permission.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 429
The interview was created.
Response Headers
Requests allowed in the current window for this key.
Requests left in the current window.
The request is malformed, or a field failed validation.
The key is missing, malformed, expired or revoked.
The key is valid but may not do this: the role it acts as lacks the permission this call needs (forbidden,
with the permission in required), or the workspace's plan has lapsed (billing_past_due: reads still work,
adding candidates is paused) or is suspended (account_suspended).
The job does not exist, or this key cannot see it.
Either the job is not active (job_not_active), its workflow does not open with an AI interview round
(job_not_interview_ready), or a request with this Idempotency-Key is still running
(request_in_progress).
The candidate could not be added. See details.failed for why, the same shape Submit candidates uses.
Too many requests. Wait for Retry-After seconds, then retry.
Response Headers
Seconds to wait before retrying.