Entretiens

Gérez les entretiens vocaux IA — listez, consultez et créez des sessions d'entretien.

Scope requis : interviews:read pour la lecture, interviews:write pour la création.

Lister les entretiens

GET/api/v1/interviews

Retourne la liste paginée des entretiens de l'organisation.

Query Parameters

Paramètre	Type	Requis	Description
`page`	integer	Non	Numéro de page (défaut : 1).
`pageSize`	integer	Non	Résultats par page — max 100 (défaut : 20).
`status`	string	Non	Filtrer par statut : DRAFT \| INVITED \| IN_PROGRESS \| COMPLETED \| CANCELLED \| EXPIRED.
`jobId`	string	Non	Filtrer par offre d'emploi.
`campaignId`	string	Non	Filtrer par processus de recrutement.

Requête

Réponse 200

Obtenir un entretien

GET/api/v1/interviews/:id

Retourne le détail complet d'un entretien, incluant l'évaluation et la transcription.

Path Parameters

Paramètre	Type	Requis	Description
`id`	string	Oui	Identifiant unique de l'entretien.

Requête

Réponse 200

Créer un entretien

POST/api/v1/interviews

Crée un nouvel entretien et envoie l'invitation au candidat.

Body Parameters

Paramètre	Type	Requis	Description
`candidateId`	string	Oui	Identifiant du candidat.
`jobId`	string	Oui	Identifiant de l'offre d'emploi.
`campaignId`	string	Non	Processus de recrutement associé.
`stageId`	string	Non	Étape du pipeline à laquelle rattacher l'entretien.
`configId`	string	Non	Identifiant de la configuration d'entretien à utiliser.
`expiresAt`	string (ISO 8601)	Non	Date d'expiration du lien d'invitation (défaut : 7 jours).
`sendInvite`	boolean	Non	Envoyer l'email d'invitation au candidat (défaut : true).

bash

Réponse 201

Workflow de l'agent IA

L'agent vocal Python utilise une série d'endpoints internes pour conduire un entretien en temps réel. Ces routes ne font pas partie de l'API v1 publique mais sont documentées ici pour les intégrations avancées et la compréhension du flux de données.

Ces endpoints requièrent le header interne X-Agent-Secret ou un token LiveKit valide. Ils ne sont pas accessibles avec une clé API standard.

Tours de parole

POST/api/interviews/:id/turns

Enregistre un tour de parole de l'agent ou du candidat. Utilisé par l'agent en temps réel à chaque échange vocal.

Body — Créer un tour

Paramètre	Type	Requis	Description
`turnNumber`	integer	Oui	Numéro séquentiel du tour (1, 2, 3…).
`role`	string	Oui	Locuteur : 'agent' \| 'candidate'.
`content`	string	Non	Transcription textuelle du tour (peut être vide si en cours).
`audioUrl`	string	Non	URL de l'enregistrement audio du tour.
`isPendingQuestion`	boolean	Non	Marque ce tour comme question pendante (l'agent attend la réponse).
`evaluation`	object	Non	Résultat de l'évaluation GPT-4o pour ce tour (scores par critère, flags).

Exemple — question agent

Exemple — réponse candidat

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

Met à jour un tour existant — typiquement pour ajouter la transcription finale et l'évaluation après que le candidat a fini de répondre.

Body

Paramètre	Type	Requis	Description
`content`	string	Non	Transcription finale corrigée.
`audioUrl`	string	Non	URL audio définitive (post-processing).
`evaluation`	object	Non	Résultat d'évaluation GPT-4o mis à jour.

GET/api/interviews/:id/history

Retourne l'historique complet des tours de parole pour un entretien. Utilisé par l'agent au redémarrage et par les clients pour afficher la transcription.

Réponse 200

Finaliser un entretien

POST/api/interviews/:id/finalize

Clôture l'entretien, génère le rapport IA et la scorecard. Déclenché automatiquement par l'agent à la fin de la conversation.

Body Parameters

Paramètre	Type	Requis	Description
`endedAt`	string (ISO 8601)	Non	Heure de fin effective de l'entretien.
`audioUrl`	string	Non	URL de l'enregistrement audio complet.
`generateReport`	boolean	Non	Déclencher la génération du rapport IA (défaut : basé sur la config de l'étape).

Requête

Réponse 200

Après finalisation, le recruteur peut accéder au rapport via GET /api/v1/reports/:reportId et au rapport enrichi via la page de résultats de l'entretien dans l'interface recruteur.

Questions fréquentes

Non. Un entretien avec le statut COMPLETED est définitif. Créez un nouvel entretien pour le même candidat si nécessaire.

Le champ audioUrl dans la réponse de GET /api/v1/interviews/:id contient le lien vers l'enregistrement complet.

Oui, utilisez le champ expiresAt (ISO 8601) lors de la création. L'invitation est envoyée immédiatement mais le candidat peut rejoindre jusqu'à la date d'expiration.

Ces endpoints sont utilisés en interne par l'agent IA vocal. Ils ne sont pas exposés via l'API v1 publique. Pour accéder à la transcription et aux évaluations, utilisez GET /api/v1/interviews/:id qui inclut les champs transcript et evaluation.