Skip to main content
POST
/
agents
Create agent
curl --request POST \
  --url https://api.instaview.sk/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Senior Developer Phone Screen",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "questions": [
    "Tell me about a challenging project you worked on"
  ],
  "instructions": "Focus on communication skills and team fit",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Sales",
    "internalId": "AGENT-001"
  },
  "cefrLevel": "B1",
  "backgroundSound": "OFFICE"
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Frontend Developer Interview",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "createdAt": "2025-11-20T10:30:00Z",
  "updatedAt": "2025-11-20T10:30:00Z",
  "questions": [
    "What is your experience with React?"
  ],
  "instructions": "Focus on technical skills and previous project experience",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Sales"
  },
  "cefrLevel": "B1",
  "backgroundSound": "OFFICE"
}
Creates a new AI interview agent (also called an interview template) scoped to the API key’s company. Agents define the questions, voice characteristics, and evaluation criteria for conducting interviews.

​
Overview

Agents are AI-powered interviewers that conduct conversations with candidates. Each agent can be customized with specific questions, voice characteristics, interview type, and evaluation criteria. Once created, agents can be reused across multiple interviews.

​
Use Cases

  • Technical Screening: Create agents for technical skill assessments
  • Behavioral Interviews: Configure agents for soft skills evaluation
  • Culture Fit Assessment: Set up agents to evaluate cultural alignment
  • Initial Screening: Create quick screening agents for high-volume applications

​
Basic Agent Creation

{
  "name": "Technical Screening Agent",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "questions": [
    "Tell me about your React experience",
    "Explain microservices architecture"
  ]
}

​
Comprehensive Agent Configuration

Note: The duration field is specified in minutes (maximum 180 minutes). 
{
  "name": "Senior Engineer Technical Interview",
  "type": "ONLINE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 30,
  "questions": [
    "Describe your experience with system design",
    "Explain how you would scale a web application",
    "Tell me about a challenging technical problem you solved"
  ],
  "instructions": "Focus on technical depth and accuracy, problem-solving approach, and communication clarity"
}

​
Phone Agents

When creating an agent with type: "PHONE", you must provide a valid companyPhoneNumberId. This ID corresponds to a phone number assigned to your company that the agent will use for calls. 
{
  "name": "Phone Screening Agent",
  "type": "PHONE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 15,
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "questions": [
    "Are you available for a 30-minute call next week?",
    "What is your expected salary range?"
  ]
}

​
Background Sound

Use backgroundSound to control the ambient noise played to candidates during calls.
ValueDescription
OFFICESubtle office ambient noise (default)
OFFComplete silence
{
  "name": "Phone Screening Agent",
  "type": "PHONE",
  "focus": "SCREENING",
  "language": "EN",
  "duration": 15,
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "backgroundSound": "OFFICE",
  "questions": [
    "Are you available for a 30-minute call next week?"
  ]
}

​
Voice Options

  • ALEX (Male)
  • PETER (Male)
  • MIRIAM (Female)
  • SUE (Female)
  • VIERA (Female)
  • CASANDRA (Female)
  • SILVIA (Female)
  • MICHAEL (Male)
  • LUKE (Male)
  • EMMA (Female)
  • SARAH (Female)
  • EVA (Female)

​
Agent Focus

The focus field determines the purpose and behavior of the interview agent. There are four supported focus types:
  • GENERIC: Used for jobless interviews where candidates don’t need to be assigned to a specific job. Ideal for talent pool building, general candidate outreach, and interviews without job associations.
  • SCREENING: Initial candidate screening and assessment. Used for evaluating candidates’ qualifications and fit for specific roles.
  • OUTREACH: Candidate outreach and engagement. Used for re-engaging candidates in your database or reaching out to potential candidates.
  • LANGUAGE_TEST: Language proficiency assessment. Used for evaluating candidates’ language skills and CEFR level.

​
Example with Focus

{
  "name": "Talent Pool Agent",
  "type": "ONLINE",
  "focus": "GENERIC",
  "language": "EN",
  "duration": 30,
  "questions": [
    "Tell me about your career goals",
    "What type of opportunities are you looking for?"
  ]
}
GENERIC Focus Requirement: When using focus: "GENERIC", the candidate must NOT have any job assignments. This is required for jobless interviews. See the Create Interview documentation for more details.

​
Company Scoping

Agents are automatically scoped to your API key’s company. You can only access and use agents that belong to your company. ATS keys can access agents from companies they manage by specifying the companyId query parameter.

Agents Resource Guide

Learn about agent configuration and best practices

Interviews Resource Guide

Use agents to conduct interviews

API Reference

List and manage your agents

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
​
name
string
required

Agent name

Required string length: 2 - 100
Example:

"Senior Developer Phone Screen"

​
type
enum<string>
required

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>
required

Focus of the agent. GENERIC: For jobless interviews where candidates don't need job assignments. SCREENING: Initial candidate screening and assessment. OUTREACH: Candidate outreach and engagement. LANGUAGE_TEST: Language proficiency assessment.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

​
language
enum<string>
required

Language of the interview

Available options:
UNDEFINED,
EN,
JA,
ZH,
DE,
HI,
FR,
KO,
PT,
IT,
ES,
ID,
NL,
TR,
FIL,
PL,
SV,
BG,
RO,
AR,
CS,
EL,
FI,
HR,
MS,
SK,
DA,
TA,
UK,
RU,
HU,
NO,
VI
Example:

"EN"

​
duration
number
required

Duration of the interview in minutes

Required range: 1 <= x <= 180
Example:

30

​
questions
string[]

List of questions for the interview

Example:
[
  "Tell me about a challenging project you worked on"
]
​
instructions
string

Additional instructions for the interview

Example:

"Focus on communication skills and team fit"

​
voiceId
enum<string>

Voice ID for the AI interview

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
​
companyPhoneNumberId
string<uuid>

ID of the company phone number assignment to use for calls from this agent (CompanyPhoneNumber.id)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
metadata
object

Custom metadata for the agent (max 10KB, 5 levels deep, 50 keys)

Example:
{
  "department": "Sales",
  "internalId": "AGENT-001"
}
​
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

​
backgroundSound
enum<string>

Ambient background sound during calls (OFFICE or OFF). Defaults to OFFICE when omitted.

Available options:
OFF,
OFFICE
Example:

"OFFICE"

Response

201 - application/json
​
id
string<uuid>
required

Agent ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
name
string
required

Agent name

Example:

"Frontend Developer Interview"

​
type
enum<string>
required

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>
required

Focus of the agent. GENERIC: For jobless interviews where candidates don't need job assignments. SCREENING: Initial candidate screening and assessment. OUTREACH: Candidate outreach and engagement. LANGUAGE_TEST: Language proficiency assessment.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

​
language
enum<string>
required

Language of the interview

Available options:
UNDEFINED,
EN,
JA,
ZH,
DE,
HI,
FR,
KO,
PT,
IT,
ES,
ID,
NL,
TR,
FIL,
PL,
SV,
BG,
RO,
AR,
CS,
EL,
FI,
HR,
MS,
SK,
DA,
TA,
UK,
RU,
HU,
NO,
VI
Example:

"EN"

​
duration
number
required

Duration of the interview in minutes

Example:

30

​
createdAt
string<date-time>
required

Agent creation timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
updatedAt
string<date-time>
required

Agent last update timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
questions
string[]

List of questions for the interview

Example:
["What is your experience with React?"]
​
instructions
string

Additional instructions for the interview

Example:

"Focus on technical skills and previous project experience"

​
voiceId
enum<string>

Voice ID for the AI interview

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
​
companyId
string<uuid>

Company ID that owns the agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
metadata
object

Custom metadata

Example:
{ "department": "Sales" }
​
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

​
backgroundSound
enum<string> | null

Ambient background sound during calls (OFFICE or OFF). Null means no override is set and the default applies.

Available options:
OFF,
OFFICE
Example:

"OFFICE"