Interviews

Manage AI voice interviews: list, retrieve and create interview sessions.

Required scope: interviews:read for reading, interviews:write for creation.

List interviews

GET/api/v1/interviews

Returns the paginated list of the organization's interviews.

Query Parameters

Paramètre	Type	Requis	Description
`page`	integer	Non	Page number (default: 1).
`pageSize`	integer	Non	Results per page, max 100 (default: 20).
`status`	string	Non	Filter by status: DRAFT \| INVITED \| IN_PROGRESS \| COMPLETED \| CANCELLED \| EXPIRED.
`jobId`	string	Non	Filter by job posting.
`campaignId`	string	Non	Filter by hiring process.

Request

200 Response

Retrieve an interview

GET/api/v1/interviews/:id

Returns the full details of an interview, including the evaluation and transcript.

Path Parameters

Paramètre	Type	Requis	Description
`id`	string	Oui	Unique identifier of the interview.

Request

200 Response

Create an interview

POST/api/v1/interviews

Creates a new interview and sends the invitation to the candidate.

Body Parameters

Paramètre	Type	Requis	Description
`candidateId`	string	Oui	Candidate identifier.
`jobId`	string	Oui	Job posting identifier.
`campaignId`	string	Non	Associated hiring process.
`stageId`	string	Non	Pipeline stage to attach the interview to.
`configId`	string	Non	Identifier of the interview configuration to use.
`expiresAt`	string (ISO 8601)	Non	Expiration date of the invitation link (default: 7 days).
`sendInvite`	boolean	Non	Send the invitation email to the candidate (default: true).

bash

201 Response

AI agent workflow

The Python voice agent uses a series of internal endpoints to conduct an interview in real time. These routes are not part of the public v1 API but are documented here for advanced integrations and to clarify the data flow.

These endpoints require the internal header X-Agent-Secret or a valid LiveKit token. They are not accessible with a standard API key.

Conversation turns

POST/api/interviews/:id/turns

Records a conversation turn from the agent or the candidate. Used by the agent in real time at each voice exchange.

Body: create a turn

Paramètre	Type	Requis	Description
`turnNumber`	integer	Oui	Sequential turn number (1, 2, 3…).
`role`	string	Oui	Speaker: 'agent' \| 'candidate'.
`content`	string	Non	Text transcript of the turn (may be empty if in progress).
`audioUrl`	string	Non	URL of the turn's audio recording.
`isPendingQuestion`	boolean	Non	Marks this turn as a pending question (the agent is waiting for the answer).
`evaluation`	object	Non	GPT-4o evaluation result for this turn (per-criterion scores, flags).

Example: agent question

Example: candidate answer

PATCH/api/interviews/:id/turns/:turnNumber

Updates an existing turn, typically to add the final transcript and evaluation after the candidate has finished answering.

Body

Paramètre	Type	Requis	Description
`content`	string	Non	Final corrected transcript.
`audioUrl`	string	Non	Final audio URL (post-processing).
`evaluation`	object	Non	Updated GPT-4o evaluation result.

GET/api/interviews/:id/history

Returns the full history of conversation turns for an interview. Used by the agent on restart and by clients to display the transcript.

200 Response

Finalize an interview

POST/api/interviews/:id/finalize

Closes the interview and generates the AI report and the scorecard. Triggered automatically by the agent at the end of the conversation.

Body Parameters

Paramètre	Type	Requis	Description
`endedAt`	string (ISO 8601)	Non	Actual end time of the interview.
`audioUrl`	string	Non	URL of the full audio recording.
`generateReport`	boolean	Non	Trigger AI report generation (default: based on the stage configuration).

Request

200 Response

After finalization, the recruiter can access the report via GET /api/v1/reports/:reportId and the enriched report via the interview results page in the recruiter interface.

Frequently asked questions

No. An interview with the COMPLETED status is final. Create a new interview for the same candidate if needed.

The audioUrl field in the GET /api/v1/interviews/:id response contains the link to the full recording.

Yes, use the expiresAt field (ISO 8601) when creating it. The invitation is sent immediately but the candidate can join up until the expiration date.

These endpoints are used internally by the AI voice agent. They are not exposed through the public v1 API. To access the transcript and evaluations, use GET /api/v1/interviews/:id, which includes the transcript and evaluation fields.