Sessions

The interview itself, with its transcript, recording and integrity timeline.

Every invitation has one session. Scope: results:read.

The session object

Field	Type
`id`	string	`ses_…`
`object`	`"session"`
`status`	string	`pending`, `in_progress`, `processing`, `completed`, `aborted`, `expired` or `cancelled`. See Concepts.
`invitation_id`	string
`interviewer_id`	string
`candidate_id`	string
`kind`	string or null	The interview format
`attempt_number`	integer
`started_at`, `completed_at`	timestamp or null
`duration_seconds`	integer or null
`ended_by`	string or null	What ended the interview, for example the candidate or a time limit
`has_recording`, `has_screen_recording`	boolean
`result_id`	string or null	Set once the session is scored
`external_ref`	string or null	From the invitation
`livemode`	boolean
`created_at`	timestamp

New statuses may be added. Treat a value you do not recognise as "other" rather than failing.

List sessions

GET /sessions. Filters: interviewer_id, candidate_id, status, external_ref, created_gte, created_lt.

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

Retrieve a session

GET /sessions/{id}

Session result

GET /sessions/{id}/result returns the session's result. Before scoring finishes, the result has status: "pending" and null scores.

Transcript

GET /sessions/{id}/transcript

{
  "object": "transcript",
  "session_id": "ses_…",
  "messages": [
    { "role": "assistant", "content": "Tell me about a system you designed.", "recording_offset_ms": 4200 },
    { "role": "user", "content": "At my last job I…", "recording_offset_ms": 9800 }
  ]
}

role is assistant for the interviewer and user for the candidate. recording_offset_ms lines each message up with the recording.

Recording

GET /sessions/{id}/recording returns signed MP4 links, valid for one hour. url is the camera recording and screen_url the screen share; either can be null. When neither exists yet you get 404 recording_not_available. Request fresh links rather than storing them.

Integrity events

GET /sessions/{id}/events lists the integrity timeline for the current attempt, oldest first, up to 500 entries: tab switches, focus loss, fullscreen exits and similar. Each entry has type, severity, source, phase, occurred_at, recording_offset_ms and review_status.

These are signals for a reviewer to check against the recording, not conclusions.