Skip to main content

Interview API quickstart

This guide runs a complete interview end-to-end: create a persona, start a session for a candidate, hand them the link, and review the results in-platform.

Prerequisites​

  • An API key from the ZenHire dashboard (zh_api_…), sent as the X-API-Key header.
  • The interview permission on your client. Contact support if calls return MISSING_PERMISSION.
  • A non-empty credit balance (interview sessions are credit-billed).

Step 1 — Create a persona​

A persona is the reusable interviewer config: a role and an interview language. Create it once and reuse it for every candidate for that role.

curl -X POST "https://platform.zenhire.ai/api/v1/interview/personas" \
  -H "X-API-Key: zh_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "Senior Backend Engineer",
    "language": "en"
  }'

Response (HTTP 201):

{
  "id": "0f2c9e2a-7b1d-4a8e-9b3c-1f2a3b4c5d6e",
  "client_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "role_name": "Senior Backend Engineer",
  "language": "en",
  "status": "active",
  "created_at": "2026-05-29T10:00:00.000Z"
}

Save the id — you'll start sessions against it.

Step 2 — Start a session​

Start a session for one candidate. This mints a candidate link and returns the session_id you'll use to fetch results.

curl -X POST \
  "https://platform.zenhire.ai/api/v1/interview/personas/0f2c9e2a-.../sessions" \
  -H "X-API-Key: zh_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_mode": "explicit",
    "candidate_ref": "candidate-12345"
  }'

Response (HTTP 201):

{
  "session_id": "7c3a1b2d-9e8f-4a6b-8c1d-2e3f4a5b6c7d",
  "candidate_link": "https://interview.zenhire.ai/#t=Zk9xQ2pYb1pUcWp5d3R...",
  "expires_in": 604800
}

The candidate_link carries a token in the URL fragment (#t=), so it is never sent to a server by a link preview or an email scanner. The token is per-candidate (it admits one candidate to one interview; reloads and brief reconnects are tolerated) and expires after expires_in seconds (7 days). The raw token is returned only here — store the session_id, send the candidate the candidate_link.

Step 3 — Send the candidate the link​

Deliver candidate_link to the candidate by any channel — email, SMS, or your own UI. When they open it:

  • If consent_mode was explicit, they see a consent gate first.
  • They allow microphone access and start the interview.
  • They have a real-time conversation with the AI interviewer, with on-screen live captions.

The session flips from initiated to active the moment the candidate starts. Nothing is required from you during the interview.

Step 4 — Review the results​

Once the interview ends the session reaches completed. Poll the session until then:

curl "https://platform.zenhire.ai/api/v1/interview/sessions/7c3a1b2d-..." \
  -H "X-API-Key: zh_api_YOUR_KEY"
{
  "id": "7c3a1b2d-9e8f-4a6b-8c1d-2e3f4a5b6c7d",
  "status": "completed",
  "duration_sec": 742,
  "credit_charged": 65,
  "consent_mode": "explicit",
  "candidate_ref": "candidate-12345",
  "completed_at": "2026-05-29T10:22:47.456Z"
}

Then fetch the recording and transcript. Both are proxied server-to-side so they stay on the platform domain — the recording streams back as audio bytes, the transcript as JSON:

# Recording → audio bytes (audio/wav). Save it or point a player at the URL.
curl "https://platform.zenhire.ai/api/v1/interview/sessions/7c3a1b2d-.../recording" \
  -H "X-API-Key: zh_api_YOUR_KEY" \
  -o interview.wav

# Transcript → JSON document.
curl "https://platform.zenhire.ai/api/v1/interview/sessions/7c3a1b2d-.../transcript" \
  -H "X-API-Key: zh_api_YOUR_KEY"
# → { ...transcript JSON... }

See Results for details.

Next steps​

  • Personas — manage reusable interviewer configs.
  • Sessions — the candidate-token model and consent.
  • Completion webhook — how a session reaches completed.
  • Results — recording and transcript retrieval.