Interview API overview

The Interview module is one of four modules on the ZenHire API Platform, alongside Speech Analysis, CV DeepMatch, and CV DeepSearch. It lets you run AI voice interviews for your candidates without building or hosting any real-time audio infrastructure yourself.

The integration model is platform-as-control-plane: you talk to the ZenHire platform over a small REST surface, the platform mints a candidate link, and ZenHire's interview backend runs the live conversation in the candidate's browser. You review the recording and transcript in-platform when the interview ends.

Base URL: https://platform.zenhire.ai/api/v1/interview

The candidate flow

1. Recruiter creates a persona        POST /api/v1/interview/personas
   (role + interview language)         → persona_id

2. Recruiter starts a session         POST /api/v1/interview/personas/:id/sessions
   for one candidate                   → session_id + candidate_link (#t=<token>)

3. Recruiter sends the candidate link  (email / SMS / your own UI)

4. Candidate opens the link            → consent gate (if explicit) → live AI
                                          interview with on-screen captions

5. Interview ends                      → ZenHire records the outcome
                                          (recording + transcript), deducts credits

6. Recruiter reviews results           GET /api/v1/interview/sessions/:id
   in-platform                         GET .../recording  GET .../transcript

You only ever touch steps 1, 2, and 6. Steps 4–5 happen between the candidate's browser and ZenHire's interview backend — your servers never sit on the real-time audio path.

Core concepts

Concept	What it is
Persona	A reusable interviewer configuration — a role name + an interview language. The AI system prompt is generated by ZenHire (v1 prompt is templated; you don't author it). One persona drives any number of candidate sessions.
Session	One interview for one candidate against one persona. Creating a session mints a candidate link.
Candidate link	`https://interview.zenhire.ai/#t=<token>` — a per-candidate, time-limited link you hand to the candidate. The token rides in the URL fragment (`#t=`), so it never leaks to a server via a link preview or scanner.
Results	The recording and transcript of a completed session, served back to you in-platform via short-lived URLs.

Authentication

Authenticate every call with your platform API key in the X-API-Key header — the same model as Speech, CV DeepMatch, and CV DeepSearch. Your client needs the interview permission enabled; calls without it return MISSING_PERMISSION.

X-API-Key: zh_api_…

An API key is pinned to its own client (no cross-tenant access), and sessions you start with a key are tagged as API requests and inherit the key's project. (The same endpoints also back the ZenHire console UIs, which use a logged-in browser session instead — both modes share one contract.)

See Authentication for key management.

Session statuses

Status	Meaning
`initiated`	Session created and a candidate link minted; the candidate hasn't started yet.
`active`	The candidate opened the link; the interview is in progress.
`completed`	The interview ended normally; recording and transcript are available.
`failed`	The session failed; no credits are charged.

Every session declares a consent_mode:

explicit — the candidate frontend shows a consent gate before the interview starts, and ZenHire captures consent.
integrator — you (the ATS) have already captured consent contractually, so no gate is shown.

Candidate voice recordings are sensitive PII — pick the mode that matches your legal posture. See Sessions for where the parameter goes.

Credits

Interviews are billed at the per-minute interview rate (rounded up to the next minute) on the same shared credit ledger as Speech and CV DeepMatch. Starting a session requires a minimum credit balance; credits are deducted only when a session completes (failed sessions are never charged). See Credits.

Error responses

All v1 interview endpoints use the platform's structured error envelope:

{
  "error": {
    "code": "MISSING_PERMISSION",
    "message": "Your account doesn't have the 'interview' permission enabled.",
    "timestamp": "2026-05-29T10:00:00.000Z",
    "details": {}
  }
}

The full endpoint reference is the Interview API section in the API reference sidebar.

The candidate flow​

Core concepts​

Authentication​

Session statuses​

Consent​

Credits​

Error responses​