Agents

Overview

Agents (also called Interview Templates) are AI-powered interviewers that conduct conversations with candidates. Each agent can be customized with specific questions, voice characteristics, instructions and focus.

Resource Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Screening Agent",
  "instructions": "Evaluates technical skills for software engineering roles",
  "voiceId": "ALEX",
  "type": "ONLINE",
  "focus": "SCREENING",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000", // Required if type is PHONE
  "backgroundSound": "OFFICE", // "OFFICE" or "OFF" — applies to all agent types
  "questions": [
    "Tell me about your experience with React and modern frontend development",
    "Explain how you would design a scalable microservices architecture",
    "Describe a challenging technical problem you solved recently",
  ],
  "duration": 30, // in minutes (max 180)
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
}

Creating Agents

const agent = await fetch("https://api.instaview.sk/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Senior Frontend Developer",
    voiceId: "ALEX",
    type: "ONLINE",
    focus: "SCREENING",
    questions: [
      "Can you describe your experience with React?",
      "How do you optimize for performance?",
    ],
    duration: 30,
  }),
});

Best Practice: For production integrations, always implement request timeouts.

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout

try {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: controller.signal,
  });
} finally {
  clearTimeout(timeoutId);
}

Voice Options

Voice	Gender	Description
`ALEX`	Male	Clear, neutral, business-appropriate (English)
`PETER`	Male	Professional, executive tone (English)
`MIRIAM`	Female	Professional, clear (English)
`SUE`	Female	Warm, approachable tone (localized as Zuzka)
`VIERA`	Female	Clear, articulate (Slovak/Czech optimized)
`CASANDRA`	Female	Professional, clear
`SILVIA`	Female	Clear, neutral
`MICHAEL`	Male	Professional (localized as Michal)
`LUKE`	Male	Young, energetic (localized as Lukáš)
`EMMA`	Female	Warm, friendly (localized as Ema)
`SARAH`	Female	Professional, clear (localized as Sára)
`EVA`	Female	Clear, articulate

Duration: The duration field is specified in minutes. The maximum allowed duration is 180 minutes (3 hours).

Background Sound

backgroundSound controls the ambient noise played to candidates during calls. It can be set on create or updated at any time via PATCH /agents/{id}.

Value	Description
`OFFICE`	Subtle office ambient noise (default)
`OFF`	Complete silence

Agent Focus Options

The focus field determines the agent’s specialization and interview style:

SCREENING
OUTREACH
GENERIC
LANGUAGE_TEST

Initial candidate screening - Basic qualifications - Availability - Salary expectations

Best Practices

Clear Questions

Write specific, open-ended questions

Appropriate Duration

15-30 minutes for most interviews

Test First

Test agents before using in production

Iterate

Refine based on interview quality

Next Steps

Interviews

Use agents to conduct interviews

API Reference

View complete Agents API reference

Getting Started

Core Concepts

Resources

Advanced

Overview

Resource Structure

Creating Agents

Voice Options

Background Sound

Agent Focus Options

Best Practices

Clear Questions

Appropriate Duration

Test First

Iterate

Next Steps

Interviews

API Reference

​Overview

​Resource Structure

​Creating Agents

​Voice Options

​Background Sound

​Agent Focus Options

​Best Practices

Clear Questions

Appropriate Duration

Test First

Iterate

​Next Steps

Interviews

API Reference

Overview

Resource Structure

Creating Agents

Voice Options

Background Sound

Agent Focus Options

Best Practices

Next Steps