AI agents

AI agents conduct the voice interviews. Each agent has a voice, a tone, a language and custom instructions. They can be global (shared across all jobs) or tied to a specific job.

Required scope: agents:read for reading, agents:write for creating and updating.

Overview

OpenAI voices (provider: "openai")

Value	Gender	Description
marin✨	Féminine	Voix féminine naturelle et expressive - Qualité supérieure
cedar✨	Masculine	Voix masculine naturelle et expressive - Qualité supérieure
nova	Féminine	Voix féminine chaleureuse et professionnelle
shimmer	Féminine	Voix féminine douce et accueillante
coral	Féminine	Voix féminine claire et dynamique
sage	Féminine	Voix féminine posée et réfléchie
ballad	Féminine	Voix féminine mélodieuse et apaisante
echo	Masculine	Voix masculine profonde et autoritaire
onyx	Masculine	Voix masculine grave et professionnelle
ash	Masculine	Voix masculine équilibrée et naturelle
verse	Masculine	Voix masculine articulée et expressive
alloy	Neutre	Voix neutre et polyvalente
fable	Neutre	Voix neutre narrative et engageante

ElevenLabs voices 🇫🇷 (provider: "elevenlabs")

High-quality native French voices

Value	Gender	Description
kev✨	Masculine	Voix masculine française naturelle et engageante
souni✨	Féminine	Voix féminine française chaleureuse et professionnelle
nova_el	Féminine	Voix féminine française expressive et dynamique
peter	Masculine	Voix masculine française claire et rassurante
jeremy	Masculine	Voix masculine française authentique et posée
camille	Féminine	Voix féminine française élégante et confiante

Available tones (tone)

Value	Description
professional	Formal, direct, recommended default
friendly	Friendly, approachable
formal	Very formal, strictly polite register
casual	Relaxed, casual
empathetic	Caring, attentive

Vigilance levels (suspicionLevel)

Value	Behavior
0	Disabled, no detection
1	Low, subtle flags (default)
2	Medium, follow-up questions when suspicious
3	Maximum, interview may be interrupted

The ElevenLabs voices ( kev, souni, camille… ) deliver higher quality for native French. The OpenAI voices marin and cedar ✨ are the newest and are recommended for multilingual use.

List agents

GET/api/agents

Returns all agents in the organization, along with the number of associated interviews and configurations.

Query Parameters

Paramètre	Type	Requis	Description
`jobId`	string	Non	Filter by job posting.
`isDefault`	boolean	Non	true to return only the default agents.

Request

Response 200

Get an agent

GET/api/agents/:id

Returns the details of an agent with its 20 most recent interviews and its associated configurations.

Path Parameters

Paramètre	Type	Requis	Description
`id`	string	Oui	Agent identifier.

Request

Response 200

Create an agent

POST/api/agents

Creates a new AI agent for the organization.

Body Parameters

Paramètre	Type	Requis	Description
`name`	string	Oui	Agent display name (e.g. "Alexandre").
`voice`	string	Non	OpenAI TTS voice (see table), default: nova.
`tone`	string	Non	Conversational tone (see table), default: professional.
`language`	string	Non	Agent language: fr \| en \| es \| de \| it, default: fr.
`instructions`	string	Non	Free-form instructions injected into the system prompt. Tell the agent its role, the industry and the priority topics.
`suspicionLevel`	integer	Non	Anti-cheating vigilance level: 0 to 3, default: 1.
`jobId`	string	Non	Link the agent to a job posting (optional, null = global agent).
`isDefault`	boolean	Non	Set as the default agent for the linked job, default: false.
`isGlobal`	boolean	Non	Make the agent available for all of the organization's jobs, default: false.
`config`	object	Non	Advanced configuration (rubric, style, guidelines, persona), see the example below.

Request, full HR agent

Response 201

Update an agent

PUT/api/agents/:id

Updates one or more fields of an agent. All fields are optional; only the fields you provide are changed.

Body Parameters

Paramètre	Type	Requis	Description
`name`	string	Non	New agent name.
`voice`	string	Non	New voice (see the table of available voices).
`tone`	string	Non	New conversational tone.
`language`	string	Non	New language.
`instructions`	string	Non	New system instructions.
`suspicionLevel`	integer	Non	New vigilance level (0-3).
`isEnabled`	boolean	Non	Enable / disable the agent.
`isDefault`	boolean	Non	Reset as the default agent.
`config`	object	Non	New advanced configuration (fully replaces the existing one).

Request, change voice and tone

Response 200

PATCH /api/agents/:id is an alias of PUT /api/agents/:id ; they behave identically.

Delete an agent

DELETE/api/agents/:id

Deletes an agent. If interviews are associated with it, the deletion is a soft delete (isDefault → false, the agent is kept in the database).

Request

Response 200, permanent deletion

Response 200, soft delete (existing interviews)

Frequently asked questions

voice is the OpenAI text-to-speech voice (timbre, accent), for example "echo" (masculine, RP) or "nova" (feminine). tone is the agent's conversational stance (professional, friendly, formal…). The two are independent and can be combined.

Yes. Several agents can be linked to the same jobId. Only one can have isDefault: true per job. If an interview does not specify an agentId, the job's default agent is used.

config is a free-form JSON object that can store: the evaluation rubric (rubric), the conversation style (style), additional guidelines (guidelines) and the agent's personality (persona.name, persona.traits). This field is passed directly into the agent's system prompt.

If the agent has associated interviews, the deletion is a soft delete: the agent is kept but isDefault is set to false. If no interview is attached to it, the agent is permanently deleted.