Update Agent - InstaView API

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,
  "cefrLevel": "B2",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Engineering"
  },
  "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"
}

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,
  "cefrLevel": "B2",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "department": "Engineering"
  },
  "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"
}

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
backgroundSound: Ambient background sound during calls (OFFICE or OFF)

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

Background Sound

Use backgroundSound to change the ambient noise played during calls for this agent. Accepted values are "OFFICE" (subtle office noise, default) and "OFF" (silence).

PATCH /agents/{id}
{
  "backgroundSound": "OFF"
}

Omitting backgroundSound keeps the existing value on the agent.

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

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

backgroundSound

enum<string> | null

Ambient background sound during calls (OFFICE or OFF). Omit to keep the existing value, set null to clear override.

Available options:

OFF,

OFFICE

Example:

"OFFICE"

Response

200 - application/json

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

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"

Get Agent Delete Agent

​Overview

​Use Cases

​Partial Updates

​Fields That Can Be Updated

​Company Isolation

​Phone Agents

​Background Sound

​Impact on Existing Interviews

​Error Scenarios

​Related Resources

Agents Resource Guide

Get Agent

Create Agent

Authorizations

Path Parameters

Query Parameters

Body

Response

Overview

Use Cases

Partial Updates

Fields That Can Be Updated

Company Isolation

Phone Agents

Background Sound

Impact on Existing Interviews

Error Scenarios

Related Resources