Interview Process States, Events

Overview

This document defines the canonical interview flow and its associated event model. It standardizes how the system tracks interview progress, transitions states, and determines terminal outcomes.

All events in this document are append-only, immutable, and ordered by timestamp.

Event Payload & Realtime Interview Status

This section defines the canonical event payload schema and the realtime interview status model

Event Payload Schema

Every interview-related event MUST conform to the following payload structure.

{
  "interviewId": "uniqueId",
  "currentStatus": "INTERVIEW_COMPLETED", // Old status of the interview (SCHEDULED, STARTED, NO_SHOW, CANDIDATE_DROP_OFF, INTERVIEW_COMPLETED, REPORT_GENERATED)
  "jobId": "NON_STEM",
  "candidateEmailId": "joenewsman@gmail.com",
  "timestamp": "2025-12-09T14:46:59Z",
  "roleTitle": "Role Title (from Turing)",
  "eventName": "Event Name (from Qode)",
  "eventValue": "Event Value (from Qode)",
  "realtimeStatus": "INTERVIEW_COMPLETED", // New status of the interview (INTERVIEW_SCHEDULED, INTERVIEW_CREATED, INTERVIEW_GETTING_READY, INTERVIEW_STARTED, INTERVIEW_LOCKED, INTERVIEW_COMPLETED, etc.)
  "isTerminal": true
}

Field Definitions

Core Identifiers

interviewId Unique identifier for the interview (shared across all attempts). And create another interviewId if send the same payload again.
jobId Interview type: STEM, NON-STEM, SWE, DOCKER, DS
candidateEmailId Candidate email address used for identification and notifications.

Event Metadata

eventName Canonical event name emitted by Qode (example: create_attempt, candidate_ready, attempt_end, abandon).
eventValue Optional contextual data for the event (example: failure reason, button clicked, system signal).
timestamp UTC timestamp indicating when the event occurred.

Realtime State Fields

currentStatus Old interview status that we don’t use anymore in new event flow. In the future, we will use realtimeStatus.
realtimeStatus The new realtime interview status, derived from the event stream.
isTerminal Boolean indicating whether the interview can progress further.

All Realtime Status Values

Realtime Status	Meaning	Terminal
`INTERVIEW_SCHEDULED`	Interview scheduled but not yet accessed	No
`INTERVIEW_CREATED`	Interview is created	No
`INTERVIEW_GETTING_READY`	Device checks and warm-up in progress	No
`INTERVIEW_STARTED`	Interview actively running with Tracy	No
`INTERVIEW_LOCKED`	Interview locked from further actions	No
`INTERVIEW_COMPLETED`	Interview finalized and report ready	Yes
`INTERVIEW_TECH_FAILURE`	Terminated due to technical failure	Yes
`INTERVIEW_ABANDONED`	Candidate disengaged	Yes
`INTERVIEW_TIMEOUT`	Interview expired	Yes
`INTERVIEW_CONNECTION_FAILURE`	Network-related termination	Yes

Canonical Event Model

Each row represents a canonical event emitted during the interview lifecycle.

event	description	frequency	semantic_meaning	real_time_status	is_terminal	terminal_reason	what_comes_next	example_utc_timestamp
`create_interview_link`	Return an unique interview_id	Once	Turing sends an API request to create an interview	INTERVIEW_SCHEDULED	FALSE	NONE	link_opened

`link_opened`	Candidate opens interview link and loading the preparing page.	Once per attempt	Candidate signals intent to start	INTERVIEW_CREATED	FALSE	NONE	create_attempt	2025-01-14T10:00:05Z
`create_attempt`	One interview_id can have multiple attempts	Once per attempt	System starts a fresh attemp	INTERVIEW_CREATED	FALSE	NONE	start_device_check	2025-01-14T10:00:12Z
`tracy_joined`	AI interviewer joins room	Once per attempt	Interview context initialized	INTERVIEW_CREATED	FALSE	NONE	independent step in backend	2025-01-14T10:00:14Z

`has_camera_device`	Can get candidate’s camera device	Send everytime it triggers with UPDATED_CAMERA_DEVICE	Camera hardware is updated	INTERVIEW_GETTING_READY	FALSE	NONE	device_check_passed	2025-01-14T10:00:18Z
`has_mic_device`	Can get candidate’s microphone device	Send everytime it triggers with UPDATED_MICROPHONE_DEVICE	Microphone hardware is updated	INTERVIEW_GETTING_READY	FALSE	NONE	device_check_passed	2025-01-14T10:00:21Z
`device_check_passed`	Have camera and microphone permission	Send everytime it triggers when have both camera and mic granted permission	System confirms technical eligibility	INTERVIEW_GETTING_READY	FALSE	NONE	candidate_ready	2025-01-14T10:00:23Z

`candidate_ready`	Candidate clicks Start Button and can join the meeting room. Log from Tracy.	Send everytime it triggers, candidate can reload and rejoin again	Candidate explicitly consents to proceed	INTERVIEW_GETTING_READY	FALSE	NONE	face_detected	2025-01-14T10:01:10Z
`face_detected`	Face detected with Tracy present	Send everytime it triggers with enum [CANDIDATE_FACE_IN_BOX, CANDIDATE_NO_FACE_DETECTED, CANDIDATE_FACE_OUTSIDE_BOX]	Candidate visually present	INTERVIEW_GETTING_READY	FALSE	NONE	speech_detected	2025-01-14T10:01:12Z
`speech_detected`	Speech detected during warm-up	Once per attempt [END_WARM_UP, ERROR_IN_WARM_UP]	Microphone usable for interview	INTERVIEW_GETTING_READY	FALSE	NONE	first_question	2025-01-14T10:01:20Z

`first_question`	First interview question delivered after warm-up with token start_interview	Once per attempt when Tracy generates start_interview	Interview content begins	INTERVIEW_STARTED	FALSE	NONE	attempt_end	2025-01-14T10:01:21Z
`attempt_end`	end_interview has been generated	Once per attempt when Tracy generates end_interview	Tracy speaks outro and the attempt has concluded	INTERVIEW_LOCKED	FALSE	NONE	report_generated	2025-01-14T10:28:40Z
`tracy_left`	When Tracy left the room	Once per attempt when Tracy left		INTERVIEW_LOCKED	FALSE	NONE	report_generated	2025-01-14T10:28:45Z

`report_generated`	Interview marked completed	Once per attempt	Successful terminal outcome	INTERVIEW_COMPLETED	TRUE	SUCCESS		2025-01-14T10:30:00Z

Interview Attempt – Event-Driven Swimlane (Happy Path)

View the interactive flow:
Interview Event Swimlane Diagram (Whimsical)

An interview attempt progresses through six ordered phases, from link access to terminal completion.

Interview Link Exists
Audio and Video Permissions Screen
Candidate Clicks Start
Interview with Tracy
Interview Ends
Completed

Each phase emits canonical events that may:

Update the authoritative interview state
Trigger downstream processing
Transition the attempt into a terminal outcome

All interview behavior is driven by events. States are derived from the event stream and are never written directly.

Happy Path (Successful Completion)

The happy path represents a fully completed interview where the candidate reaches the natural end of the session. Key characteristics

Tracy completes the interview flow
<end_token> is generated
The attempt ends normally
Scoring and finalization proceed

Canonical events

attempt_end → Tracy speaks outro and generates <end_token>
report_generated

Completed State Rules

Once a report_generated event is emitted:

The interview attempt is completed
All artifacts (transcript, scores, report) are ready
The interview link cannot be reused to create a new attempt

Interview Attempt – Failure & Exit Paths (Non-Happy Path)

This section defines all failure and early-exit paths for an interview attempt. These paths represent terminal conditions where the interview cannot continue and can be retried using the same link.

Failure and exit events are authoritative. Once emitted, the interview attempt immediately transitions to a terminal state.

Failure & Exit Flow Overview

An interview attempt may terminate from any active phase, including:

Device check failed
Candidate drops mid-interview
Interview times out
Connection failure

Each path emits a single canonical failure or exit event, followed by interview finalization when applicable.

Failure & Exit Paths

1. Device Validation Failure

Occurs during device checks when required hardware or permissions are not met. Flow

Device checks in progress
Event emitted: device_check_failed

2. Candidate Abandonment

Occurs when the candidate clicks End Interview during interview before attemp_end. Flow

Any active step
Event emitted: abandon
Interview terminates immediately

3. Interview Expiration (Timeout)

Occurs when the interview exceeds the allowed time window. Flow

Any active step
Event emitted: expire
Interview terminates

Timeouts are 10 minutes when the meeting is created if candidate doesn’t join the room.

4. Connection Failure

Occurs when the interview session drops due to network issues. Flow

Any active step
Event emitted: connection_failure
Interview terminates

Connection failures are classified separately from abandonment for analytics accuracy. If candidate left during the interview without clicking End Interview, Tracy will wait 5 minutes before leaving the interview.

Canonical Failure & Exit Events

Event	Description	Semantic Meaning	Emitted By	Client Visible	Authoritative State
`device_check_failed`	Device validation failed	Attempt cannot proceed technically	System	Yes	TERMINAL
`abandon`	Candidate clicks `End Interview` during interview before `attemp_end`	Candidate purposely wants to end the interview.	System-detected	Yes	TERMINAL
`expire`	Candidate doesn’t click `Start Interview` button after 10 minues.	System-enforced timeout	System	Yes	TERMINAL
`connection_failure`	Connection failure due to network (candidate left without clicking `End Interview`) and doesn’t rejoin within 5 minutes.	Interview interrupted by connectivity loss	System	Yes	TERMINAL

Terminal State Rules

Once a failure or exit event is emitted:

The interview attempt is irreversibly terminal
The interview link can be reused to create a new attempt

Retry & New Attempt Creation

This section defines how the system handles retries after an interview attempt reaches a terminal outcome. Retries are event-driven and always result in the creation of a new interview attempt.

An interview attempt is immutable. Retrying never reopens or modifies a previous attempt.

When a Retry Is Allowed

A retry is allowed only when the previous attempt ended in a terminal but retry-eligible state.

Retry-Eligible Terminal Outcomes

Status	Retry Allowed	Rationale
`INTERVIEW_TECH_FAILURE`	Yes	Candidate was blocked by technical issues
`INTERVIEW_CONNECTION_FAILURE`	Yes	Interview interrupted by network loss
`INTERVIEW_TIMEOUT`	Yes	Interview expired before completion
`INTERVIEW_ABANDONED`	Yes	Candidate disengaged

Non-Retryable Terminal Outcomes

Terminal Reason	Retry Allowed	Rationale
`INTERVIEW_COMPLETED`	No	Interview successfully completed

A completed interview can never be retried using the same interview link.

Getting Started

Integration API

Embedding

Interview Process States, Events

Overview

Event Payload & Realtime Interview Status

Event Payload Schema

Field Definitions

Core Identifiers

Event Metadata

Realtime State Fields

All Realtime Status Values

Canonical Event Model

Interview Attempt – Event-Driven Swimlane (Happy Path)

Happy Path (Successful Completion)

Completed State Rules

Interview Attempt – Failure & Exit Paths (Non-Happy Path)

Failure & Exit Flow Overview

Failure & Exit Paths

1. Device Validation Failure

2. Candidate Abandonment

3. Interview Expiration (Timeout)

4. Connection Failure

Canonical Failure & Exit Events

Terminal State Rules

Retry & New Attempt Creation

When a Retry Is Allowed

Retry-Eligible Terminal Outcomes

Non-Retryable Terminal Outcomes

​Overview

​Event Payload & Realtime Interview Status

​Event Payload Schema

​Field Definitions

​Core Identifiers

​Event Metadata

​Realtime State Fields

​All Realtime Status Values

​Canonical Event Model

​Interview Attempt – Event-Driven Swimlane (Happy Path)

​Happy Path (Successful Completion)

​Completed State Rules

​Interview Attempt – Failure & Exit Paths (Non-Happy Path)

​Failure & Exit Flow Overview

​Failure & Exit Paths

​1. Device Validation Failure

​2. Candidate Abandonment

​3. Interview Expiration (Timeout)

​4. Connection Failure

​Canonical Failure & Exit Events

​Terminal State Rules

​Retry & New Attempt Creation

​When a Retry Is Allowed

​Retry-Eligible Terminal Outcomes

​Non-Retryable Terminal Outcomes

Overview

Event Payload & Realtime Interview Status

Event Payload Schema

Field Definitions

Core Identifiers

Event Metadata

Realtime State Fields

All Realtime Status Values

Canonical Event Model

Interview Attempt – Event-Driven Swimlane (Happy Path)

Happy Path (Successful Completion)

Completed State Rules

Interview Attempt – Failure & Exit Paths (Non-Happy Path)

Failure & Exit Flow Overview

Failure & Exit Paths

1. Device Validation Failure

2. Candidate Abandonment

3. Interview Expiration (Timeout)

4. Connection Failure

Canonical Failure & Exit Events

Terminal State Rules

Retry & New Attempt Creation

When a Retry Is Allowed

Retry-Eligible Terminal Outcomes

Non-Retryable Terminal Outcomes