Skip to main content
PATCH
/
agents
/
{id}
Update agent
curl --request PATCH \
  --url https://api.instaview.sk/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated Senior Developer Interview",
  "type": "ONLINE",
  "focus": "SCREENING",
  "questions": [
    "What is your experience with React?"
  ],
  "instructions": "Focus on system design and communication",
  "language": "EN",
  "duration": 45,
  "voiceId": "ALEX",
  "cefrLevel": "B2",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Engineering"
  }
}
'
{
  "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",
  "voiceId": "ALEX",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Sales"
  },
  "cefrLevel": "B1"
}
Updates an existing agent (interview template) using partial updates. Only provided fields will be updated; omitted fields remain unchanged.

​
Overview

The update agent endpoint allows you to modify agent configuration without recreating it. This supports partial updates, meaning you only need to provide the fields you want to change. This is useful for refining agent questions, updating evaluation criteria, or adjusting voice settings.

​
Use Cases

  • Refine Questions: Update interview questions based on feedback
  • Adjust Settings: Change voice, duration, or interview type
  • Update Criteria: Modify evaluation criteria as requirements evolve
  • Iterative Improvement: Continuously improve agent configurations

​
Partial Updates

You can update any combination of fields: 
// Update only questions
PATCH /agents/{id}
{
  "questions": [
    "New question 1",
    "New question 2"
  ]
}

// Update multiple fields
PATCH /agents/{id}
{
  "name": "Updated Agent Name",
  "focus": "SCREENING",
  "duration": 45,
  "questions": [
    "Updated question 1",
    "Updated question 2"
  ]
}

​
Fields That Can Be Updated

  • name: Agent display name
  • type: Agent type (ONLINE, PHONE)
  • focus: Agent focus (GENERIC, SCREENING, OUTREACH, LANGUAGE_TEST)
  • language: Interview language code
  • duration: Interview duration in minutes (max 180)
  • questions: Array of interview questions
  • instructions: Additional instructions for the interview
  • voiceId: Voice ID for the AI interview
  • cefrLevel: CEFR level for language test agents

​
Company Isolation

You can only update agents that belong to your API key’s company. Attempting to update an agent from another company will result in a 403 Forbidden error.

​
Phone Agents

If you update an agent’s type to PHONE, you must also provide a companyPhoneNumberId in the same request. 
PATCH /agents/{id}
{
  "type": "PHONE",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000"
}

​
Impact on Existing Interviews

Updates to agent configuration do not affect interviews that have already been scheduled or completed. Only new interviews created after the update will use the new configuration.

​
Error Scenarios

  • 404 Not Found: Agent doesn’t exist or has been deleted
  • 403 Forbidden: Agent belongs to a different company
  • 400 Bad Request: Invalid field values or validation errors

Agents Resource Guide

Learn about agent configuration best practices

Get Agent

Retrieve current agent configuration

Create Agent

Create new agents

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

​
id
string<uuid>
required

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

Agent name

Required string length: 2 - 100
Example:

"Updated Senior Developer Interview"

​
type
enum<string>

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>

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"

​
questions
string[]

List of questions for the interview

Maximum array length: 50
Example:
["What is your experience with React?"]
​
instructions
string

Additional instructions for the interview

Maximum string length: 2000
Example:

"Focus on system design and communication"

​
language
enum<string>

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

Duration of the interview in minutes

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

45

​
voiceId
enum<string> | null

Voice ID for the AI interview (null clears existing voice)

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

CEFR level for language test agents

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

"B2"

​
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 (merged with existing metadata, max 10KB, 5 levels deep, 50 keys)

Example:
{ "department": "Engineering" }

Response

200 - 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"