Skip to main content

Start a session

POST 
/api/v1/interview/personas/:personaId/sessions

Starts an interview session against a persona for one candidate and mints a candidate link.

Before the session is created, the platform runs two pre-checks: the interview permission must be enabled and the client must have at least the minimum credit balance.

Sessions started with an X-API-Key inherit that key's project attribution automatically; there is no project_id body field on this request (project selection is a console-only input).

Creating a session only mints a candidate link; it does not consume a concurrent-interview slot. You can mint as many links as you like (each is bounded only by its expires_in token TTL). The concurrent-interview cap (maxConcurrentRequests) is enforced later, when a candidate actually starts the live interview — see the session lifecycle note on the verify endpoint.

On success you receive a candidate_link of the form https://interview.zenhire.ai/#t=<token>. The token travels in the URL fragment (#t=), not a query string, so it is never sent to a server in a plain link preview or by email/link scanners. The token is:

  • per-candidate — it admits a single candidate to one interview. Reloads and brief reconnects are tolerated, but once the interview reaches a terminal state (completed/failed) the link no longer starts a new interview.
  • time-limited — it expires expires_in seconds after creation (a 7-day pre-use TTL). An unused, expired token cannot start an interview.

Maximum interview duration. Once a candidate starts the live interview, it must complete within a fixed time budget. A live interview that runs past that budget without a completion signal is automatically closed (status failed, error code SESSION_TIMEOUT), which also frees its concurrent-interview slot. A session that ended this way — or any session that ended without a result — can be re-invited from the ZenHire console, which mints a fresh candidate link.

Send the link to the candidate by whatever channel you prefer. The raw token is only ever returned in this response — the platform stores only a hash of it and never logs or re-emits it.

Request​

Responses​

Session created and a candidate link minted.