Screenings

Read-only access to screening sessions (WhatsApp, email, web form) and video interviews. List items are discriminated by type. Create video interviews via POST /api/v1/video-interviews (10 credits each). Optionally pass interview_questions to use custom questions instead of auto-generation.

List query parameters (GET)

GET /api/v1/screenings
Field	Type	Required	Description
type	"session" \| "video" \| "all"	No	Filter resource type (default all)
status	string	No	Status filter (values depend on type)
job_id	string (uuid)	No	Filter by job
candidate_id	string (uuid)	No	Filter by candidate
search	string	No	Name/email search; job title for video
channel	"whatsapp" \| "email" \| "web_form"	No	Sessions only
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

List response items

data is an array of either screening_session or video_interview objects (when type=all, merged by updated_at).

type = screening_session
Field	Type	Required	Description
id	string (uuid)	—	Session id
type	"screening_session"	—	Discriminator
channel	"whatsapp" \| "email" \| "web_form"	—	Screening channel
status	"initiated" \| "message_sent" \| "in_progress" \| "awaiting_resume" \| "completed" \| "expired" \| "cancelled"	—	Session status
candidate_id	string (uuid)	—	Candidate id
job_id	string (uuid)	—	Job id
candidate_name	string \| null	—	Candidate display name
job_title	string \| null	—	Job title
pipeline_status	string \| null	—	From candidate_jobs
match_score	number \| null	—	From candidate_jobs
calculated_score	number \| null	—	Computed screening score
current_question_index	integer	—	Progress index
email_sent_at	string (ISO 8601 date-time)	—	Email sent
email_opened_at	string (ISO 8601 date-time)	—	Email opened
form_started_at	string (ISO 8601 date-time)	—	Web form started
completed_at	string (ISO 8601 date-time)	—	Completed
expires_at	string (ISO 8601 date-time)	—	Expiry
metadata	object \| null	—	Session metadata
created_at	string (ISO 8601 date-time)	—	Created
updated_at	string (ISO 8601 date-time)	—	Updated

type = video_interview
Field	Type	Required	Description
id	string (uuid)	—	Interview id
type	"video_interview"	—	Discriminator
status	"invited" \| "in_progress" \| "completed" \| "expired" \| "abandoned"	—	Interview status
candidate_id	string (uuid)	—	Candidate id
job_id	string (uuid) \| null	—	Job id (null for resume-only)
question_source	"job" \| "resume"	—	Whether questions were generated from job/JD or candidate resume
initiated_via	"dashboard" \| "api" \| "portal" \| "apply"	—	How the interview was created
candidate_name	string \| null	—	Candidate name
job_title	string \| null	—	Job title
pipeline_status	string \| null	—	Pipeline status
match_score	number \| null	—	Match score
total_experience_years	number \| null	—	Candidate total experience
relevant_experience_years	number \| null	—	Candidate relevant experience
overall_score	number \| null	—	Overall interview score
proctoring_trust_score	number \| null	—	Proctoring trust score
proctoring_risk_level	string \| null	—	Risk level label
recording_merge_status	string \| null	—	Recording merge state
has_recording_chunks	boolean	—	Has uploaded chunks
has_valid_merge	boolean	—	Merged recording ready
current_question_index	integer	—	Current question index
started_at	string (ISO 8601 date-time)	—	Started
ended_at	string (ISO 8601 date-time)	—	Ended
expires_at	string (ISO 8601 date-time)	—	Expires
metadata	object \| null	—	Metadata
created_at	string (ISO 8601 date-time)	—	Created
updated_at	string (ISO 8601 date-time)	—	Updated

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

Detail query parameters (GET)

GET /api/v1/screenings/{id}
Field	Type	Required	Description
type	"screening_session" \| "video_interview"	Yes	Required query parameter

Detail response (nested arrays)

responses[] (screening_session detail only)
Field	Type	Required	Description
id	string (uuid)	—	Response id
question_id	string	—	Question id
question	string	—	Question text
answer	string	—	Answer text
answer_type	string	—	Answer type
score	number \| null	—	Question score
answered_at	string (ISO 8601 date-time)	—	When answered

answers[] (video_interview detail only)
Field	Type	Required	Description
question_index	integer	—	Question order
question_text	string	—	Question text
answer_transcript	string \| null	—	Transcript (detail only)
score	number \| null	—	Answer score
answered_at	string (ISO 8601 date-time)	—	Answered at

Video detail also includes proctoring_summary_json, integrity_json, and readiness_json as object | null. Recording URLs are not returned in v1.

GET/api/v1/screenings

List screenings.

GET/api/v1/screenings/{id}?type=screening_session

Session detail with responses[].

GET/api/v1/screenings/{id}?type=video_interview

Video detail with answers[].