Skip to main content
A session represents one AI interview — the conversation, the recording, the transcript, and the scorecard. Sessions are the core unit of usage and the most-handled object in the API.

​
Status lifecycle

   created       ┌──────────────┐
   ─────────────►│  scheduled   │  Session row created. AI is provisioned;
                 └─────┬────────┘  candidate has a join URL.
                       │
        candidate joins│
                       ▼
                 ┌──────────────┐  AI is conversing with the candidate.
                 │ in_progress  │  Transcript streams in; authenticity
                 └─────┬────────┘  signals captured live.
                       │
                       │
       ┌───────────────┼───────────────┐
       │               │               │
  hangs up early   completes   recruiter cancels
       ▼               ▼               ▼
 ┌──────────┐   ┌──────────┐    ┌──────────┐
 │  failed  │   │ completed│    │cancelled │
 └──────────┘   └──────────┘    └──────────┘
​
scheduled
Session row created. AI hasn’t joined yet. The candidate can join via the join_url from the invite at any time.
​
in_progress
Candidate joined and the AI is actively interviewing. Transcript + authenticity signals stream into the session record live.
​
completed
Interview finished naturally — the AI delivered the closing line and ended the call. Scorecard ready within 2 minutes.
​
failed
Candidate disconnected mid-interview, or a tech failure interrupted the session. Partial transcript may still be available; no scorecard.
​
cancelled
Recruiter cancelled the session via the API or UI before the candidate joined. No interview happened.

​
Status changes emit events

Every state transition fires a webhook. Configure your endpoint to receive them — see Webhooks for the payload shape + HMAC signing.
TransitionEvent fired
Created (via API or UI)session.created
Candidate joinssession.started
Completes naturallysession.completed
Fails / disconnectssession.failed
Cancelled by recruitersession.cancelled
Scorecard finalizedsession.scored (fires 30s–2min after completed)
Listen for session.scored, not session.completed, when you want the full rubric scorecard. session.completed fires the moment the AI hangs up; scoring happens asynchronously and session.scored is the signal that the scorecard is final.

​
Reading a session

curl "https://www.intervyo.ai/api/v1/sessions/e3a1c2d4-..." \
  -H "x-api-key: $INTERVYO_API_KEY"
Returns: 
{
  "data": {
    "id": "e3a1c2d4-...",
    "status": "completed",
    "evaluation_template_id": "ce1cd564-...",
    "candidate_id": "ba4f2cdd-...",
    "stage": "screen",
    "score": "8.2",
    "passed": true,
    "recommendation": "hire",
    "ai_feedback": "Strong candidate with clear system design...",
    "evaluation_breakdown": [
      { "name": "Technical Depth", "score": 8.5, "feedback": "..." },
      { "name": "Communication",   "score": 7.8, "feedback": "..." }
    ],
    "duration_seconds": 2740,
    "started_at": "2026-06-02T07:48:31Z",
    "ended_at": "2026-06-02T08:21:14Z"
  }
}
See Get Session for the full schema.

​
Re-runs and retries

Each session is immutable once it lands in a terminal state (completed / failed / cancelled). If you need another interview for the same candidate — say after a technical failure — create a fresh session. Sessions for the same (participant, stage) are independent rows; the platform doesn’t try to “merge” or “supersede” them. The Applications panel on each template’s detail page automatically picks the latest session per stage when displaying the rolled-up status, so retries surface immediately.

​
Multi-stage progression

Multi-stage templates auto-create a fresh session for the next stage when a candidate passes a stage. You don’t need to manually invoke this — the session-status mirror trigger handles it. A candidate’s full trajectory through a 3-stage template ends up as 3 sessions, one per stage, linked through the same candidate_id. See Templates for how stages chain together.

​
Session vs application

These are two different objects, easy to confuse:
ObjectPurpose
SessionOne conversation between AI and participant. Holds the transcript, scores, recording.
Application (template_applications)The relationship between a participant and a template. Tracks HR approval, scheduling status, and the latest session. Created by the public apply flow or by manually adding a participant to a template.
The Applications panel on the template detail page reads from template_applications, but the data shown (scores, transcripts, status) comes from the latest session joined onto the application. They’re paired 1:N — one application can have many sessions over time (retries, multi-stage progressions).
Last modified on June 2, 2026