Concepts
Interviewers, candidates, invitations, sessions and results, and how they relate.
The objects
| Object | Id prefix | What it is |
|---|---|---|
| Interviewer | int_ | An interview you designed: role, questions, rubric, duration. |
| Candidate | cand_ | A person, keyed by email within your organisation. |
| Invitation | inv_ | One candidate invited to one interviewer. Carries the link. |
| Session | ses_ | The interview itself: timing, recording, transcript. |
| Result | res_ | Scores and evidence for a completed session. |
| Import | imp_ | A spreadsheet of candidates invited in one go. |
| Export | exp_ | A CSV or Excel file of sessions or results. |
| Event | evt_ | Something that happened, delivered to your webhooks. |
An invitation and its session share the same underlying record, so invitation.session_id and session.invitation_id always point at each other. A session has at most one result.
Invitation and session status
The invitation status answers "where is this candidate?". The session status is finer grained and follows the interview itself.
Session status | Invitation status | Meaning |
|---|---|---|
pending | pending | Invited, not started. The link works. |
in_progress | started | The candidate is in the interview. |
processing | started | Finished; Heizen is scoring it. |
completed | completed | Scored. The result is ready. |
aborted | abandoned | The candidate left and did not come back. |
expired | expired | The link ran out before the candidate started. |
cancelled | canceled | You cancelled the invitation before it started. |
Invitations spell it canceled and sessions cancelled. Filter each list with its own spelling.
Links and expiry
A link lasts 14 days by default. Set expires_at when you create an invitation to choose a different time, up to 90 days out. Extend a pending or expired invitation to push the expiry out, resend to issue a fresh link (the old one stops working), or cancel to close it.
Results are evidence, not verdicts
A result holds an overall score, dimension scores, a summary, the strengths and gaps the interviewer observed, per-question scores and an integrity summary. It never contains a hire or reject recommendation. low_confidence is true when the interview was too short or too disrupted to score well; read low_confidence_reason before relying on the numbers.
Test mode and live mode
Every API key belongs to one mode. Everything it creates carries livemode: false or true, and each mode sees only its own data: a test key cannot read live invitations, and webhook endpoints only receive events from their own mode.
| Test | Live | |
|---|---|---|
| Key prefix | hz_test_ | hz_live_ |
| Interviews run for real | Yes | Yes |
Emails sent (unless send_email: false) | Yes | Yes |
| Credits used | Never | One when the candidate starts |
A candidate's email belongs to one mode. Inviting an email that already exists in the other mode fails with candidate_exists_in_other_mode, so use different addresses for testing.
Credits
A live invitation uses one credit the first time its session starts. Creating, resending or cancelling an invitation costs nothing. When credits run out, live invitation requests fail with credits_exhausted. Check your balance with GET /v1/usage or on Developers → Usage.