Quickstart

This walk-through uses a test key, so nothing you do here costs credits.

1. Create a test key

In the dashboard, open Developers → API keys, choose Test, and create a key with the interviewers:read, invitations:send and results:read scopes. Copy the key when it appears. Heizen shows it once.

Keep keys on your server. Put the key in an environment variable such as HEIZEN_API_KEY and never ship it to a browser or mobile app.

2. Check the key

curl https://api.interviewer.heizen.tech/api/v1/ping \
  -H "Authorization: Bearer $HEIZEN_API_KEY"

{ "object": "ping", "ok": true, "livemode": false, "api_version": "2026-10-01" }

3. Pick an interviewer

An interviewer is the interview you designed in the dashboard: the role, the questions and how it is scored.

curl "https://api.interviewer.heizen.tech/api/v1/interviewers?limit=5" \
  -H "Authorization: Bearer $HEIZEN_API_KEY"

Note the id of the one you want. It looks like int_….

4. Invite a candidate

curl https://api.interviewer.heizen.tech/api/v1/invitations \
  -H "Authorization: Bearer $HEIZEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: application-981" \
  -d '{
    "interviewer_id": "int_…",
    "candidate": { "email": "ada@example.com", "name": "Ada Lovelace" },
    "external_ref": "application-981",
    "send_email": false
  }'

The response is an invitation. Its url is the candidate's interview link. With send_email: false Heizen does not email it, so you can open the link yourself and take the interview. Leave send_email out to have Heizen email the candidate.

Want the link to close sooner than the default 14 days? Add "expires_at": "2026-10-15T18:00:00Z". It must be in the future and no more than 90 days away.

5. Read the result

When the interview finishes, the session moves to processing and then completed, and a result appears.

curl "https://api.interviewer.heizen.tech/api/v1/sessions?external_ref=application-981" \
  -H "Authorization: Bearer $HEIZEN_API_KEY"

curl https://api.interviewer.heizen.tech/api/v1/sessions/ses_…/result \
  -H "Authorization: Bearer $HEIZEN_API_KEY"

Polling works, but a webhook on result.ready is simpler and faster.

The same thing in TypeScript

import { Heizen } from "@heizen/interviewer";

const heizen = new Heizen({ apiKey: process.env.HEIZEN_API_KEY! });

const { data: [interviewer] } = await heizen.interviewers.list({ limit: 1 });
const invitation = await heizen.invitations.create({
	interviewer_id: interviewer!.id,
	candidate: { email: "ada@example.com", name: "Ada Lovelace" },
	external_ref: "application-981",
	send_email: false,
});
console.log(invitation.url);

See SDKs for the full client.

Going live

Create a live key (hz_live_…) with the same scopes and swap it in. Live invitations use one credit when the candidate starts the interview. Add a webhook endpoint in live mode too; test and live endpoints are separate.