> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agent
> Creates a new agent scoped to the API key's company.
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
```javascript theme={null}
{
"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).
```javascript theme={null}
{
"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.
```javascript theme={null}
{
"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.
| Value | Description |
| -------- | ------------------------------------- |
| `OFFICE` | Subtle office ambient noise (default) |
| `OFF` | Complete silence |
```javascript theme={null}
{
"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
```javascript theme={null}
{
"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](/api-reference/interviews/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.
## Related Resources
Learn about agent configuration and best practices
Use agents to conduct interviews
List and manage your agents
## OpenAPI
````yaml POST /agents
openapi: 3.0.0
info:
title: InstaView API
description: |-
InstaView API Documentation
## Authentication
All endpoints require API key authentication using Bearer token:
```
Authorization: Bearer sk_your_api_key_here
```
## API Key Management
The API Key module provides comprehensive key management for:
- **Direct Client Keys**: Company-scoped keys for your applications
- **ATS Partner Keys**: Resource-scoped keys for ATS integrations
### Key Features
- HMAC-SHA256 hashing for API key storage
- Configurable rate limiting
- Comprehensive audit logging
- Company-level isolation
- Resource scoping for ATS partners
version: 1.0.0
contact: {}
servers:
- url: https://api.instaview.sk
description: Production API Gateway
security: []
tags: []
paths:
/agents:
post:
tags:
- Agents
summary: Create agent
description: Creates a new agent scoped to the API key's company.
operationId: PublicAgentsController_createAgent_v1
parameters:
- name: companyId
required: false
in: query
description: >-
Required for ATS API keys to specify which company to access.
Ignored for standard company API keys.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateAgentDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentDto'
security:
- bearer: []
components:
schemas:
PublicCreateAgentDto:
type: object
properties:
name:
type: string
description: Agent name
example: Senior Developer Phone Screen
minLength: 2
maxLength: 100
type:
type: string
description: Type of the agent
enum:
- UNDEFINED
- ONLINE
- PHONE
example: ONLINE
focus:
type: string
description: >-
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.
enum:
- GENERIC
- SCREENING
- OUTREACH
- LANGUAGE_TEST
example: SCREENING
language:
type: string
description: Language of the interview
enum:
- 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:
type: number
description: Duration of the interview in minutes
example: 30
minimum: 1
maximum: 180
questions:
description: List of questions for the interview
example:
- Tell me about a challenging project you worked on
type: array
items:
type: string
instructions:
type: string
description: Additional instructions for the interview
example: Focus on communication skills and team fit
voiceId:
type: string
description: Voice ID for the AI interview
enum:
- ALEX
- PETER
- MIRIAM
- SUE
- VIERA
- CASANDRA
- SILVIA
- MICHAEL
- LUKE
- EMMA
- SARAH
- EVA
companyPhoneNumberId:
type: string
description: >-
ID of the company phone number assignment to use for calls from this
agent (CompanyPhoneNumber.id)
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
metadata:
type: object
description: Custom metadata for the agent (max 10KB, 5 levels deep, 50 keys)
example:
department: Sales
internalId: AGENT-001
cefrLevel:
type: string
description: CEFR level for language test agents
enum:
- A1
- A2
- B1
- B2
- C1
- C2
example: B1
backgroundSound:
type: string
description: >-
Ambient background sound during calls (`OFFICE` or `OFF`). Defaults
to `OFFICE` when omitted.
enum:
- 'OFF'
- OFFICE
example: OFFICE
required:
- name
- type
- focus
- language
- duration
PublicAgentDto:
type: object
properties:
id:
type: string
description: Agent ID
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description: Agent name
example: Frontend Developer Interview
type:
type: string
description: Type of the agent
enum:
- UNDEFINED
- ONLINE
- PHONE
example: ONLINE
focus:
type: string
description: >-
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.
enum:
- GENERIC
- SCREENING
- OUTREACH
- LANGUAGE_TEST
example: SCREENING
questions:
description: List of questions for the interview
example:
- What is your experience with React?
type: array
items:
type: string
instructions:
type: string
description: Additional instructions for the interview
example: Focus on technical skills and previous project experience
language:
type: string
description: Language of the interview
enum:
- 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:
type: number
description: Duration of the interview in minutes
example: 30
voiceId:
type: string
description: Voice ID for the AI interview
enum:
- ALEX
- PETER
- MIRIAM
- SUE
- VIERA
- CASANDRA
- SILVIA
- MICHAEL
- LUKE
- EMMA
- SARAH
- EVA
companyId:
type: string
format: uuid
description: Company ID that owns the agent
example: 123e4567-e89b-12d3-a456-426614174000
metadata:
type: object
description: Custom metadata
example:
department: Sales
cefrLevel:
type: string
description: CEFR level for language test agents
enum:
- A1
- A2
- B1
- B2
- C1
- C2
example: B1
backgroundSound:
type: string
description: >-
Ambient background sound during calls (`OFFICE` or `OFF`). Null
means no override is set and the default applies.
enum:
- 'OFF'
- OFFICE
example: OFFICE
nullable: true
createdAt:
type: string
description: Agent creation timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
updatedAt:
type: string
description: Agent last update timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
required:
- id
- name
- type
- focus
- language
- duration
- createdAt
- updatedAt
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````