> ## 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.
# List Interviews
> Lists interviews for a given candidate within the API key's company. For MVP, candidateId is required.
Lists interviews with pagination and filtering options. For MVP, the `candidateId` query parameter is required to filter interviews.
## Overview
The list interviews endpoint allows you to retrieve interviews for a specific candidate. This is useful for tracking a candidate's interview history, checking interview status, and retrieving analysis results.
## Required Filter
**MVP Requirement**: The `candidateId` query parameter is currently required. You must specify a candidate ID to list interviews. Listing all interviews without a filter is not yet supported.
## Use Cases
* **Candidate Interview History**: View all interviews for a specific candidate
* **Status Tracking**: Monitor interview progress and completion
* **Analysis Retrieval**: Access interview analysis and transcripts
* **Pipeline Management**: Track interviews across your recruitment process
## Basic Usage
```javascript theme={null}
// List all interviews for a candidate
GET /interviews?candidateId=candidate-uuid
```
## With Pagination
```javascript theme={null}
// Get first page with 20 items
GET /interviews?candidateId=candidate-uuid&page=1&limit=20
// Get second page
GET /interviews?candidateId=candidate-uuid&page=2&limit=20
```
## Status Filtering
You can filter interviews by status (when supported):
```javascript theme={null}
// Get only completed interviews
GET /interviews?candidateId=candidate-uuid&status=completed
```
## Response Structure
The response includes interview details along with analysis data (when available):
```json theme={null}
{
"success": true,
"data": {
"items": [
{
"id": "interview-uuid",
"candidateId": "candidate-uuid",
"agentId": "agent-uuid",
"status": "completed",
"analysis": {
"overallScore": 8.5,
"recommendation": "Strong hire"
}
}
],
"pagination": {
"total": 5,
"page": 1,
"limit": 20
}
}
}
```
## Tracking Interview Progress
```javascript theme={null}
async function trackCandidateInterviews(candidateId) {
const response = await fetch(
`https://api.instaview.sk/interviews?candidateId=${candidateId}`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data } = await response.json();
const completed = data.items.filter(i => i.status === 'completed');
const inProgress = data.items.filter(i => i.status === 'in_progress');
const scheduled = data.items.filter(i => i.status === 'scheduled');
return {
total: data.pagination.total,
completed: completed.length,
inProgress: inProgress.length,
scheduled: scheduled.length
};
}
```
## Company Isolation
All returned interviews belong to candidates that are associated with jobs in your API key's company. You cannot access interviews from other companies.
## Related Resources
Learn about interview management and analysis
Retrieve a specific interview by ID
Understand pagination best practices
Manage candidate profiles
## OpenAPI
````yaml GET /interviews
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:
/interviews:
get:
tags:
- Interviews
summary: List interviews
description: >-
Lists interviews for a given candidate within the API key's company. For
MVP, candidateId is required.
operationId: PublicInterviewsController_listInterviews_v1
parameters:
- name: page
required: false
in: query
description: Page number (1-based)
schema:
minimum: 1
maximum: 10000
default: 1
example: 1
type: integer
- name: limit
required: false
in: query
description: Number of items per page
schema:
minimum: 1
maximum: 100
default: 20
example: 20
type: integer
- name: companyId
required: false
in: query
description: Company ID (required for ATS keys, optional for regular keys)
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: candidateId
required: true
in: query
description: Filter by candidate ID
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: agentId
required: false
in: query
description: Filter by agent ID
schema:
example: 987e6543-e21b-12d3-a456-426614174000
type: string
format: uuid
- name: status
required: false
in: query
description: Filter by interview status
schema:
type: string
enum:
- UNDEFINED
- SCHEDULED
- CANCELLED
- FAILED
- COMPLETED
- IN_PROGRESS
example: SCHEDULED
- name: jobId
required: false
deprecated: true
in: query
description: >-
[Deprecated] Filter by job ID (through candidate). Redundant when
candidateId is required.
schema:
example: 456e7890-e12b-34d5-a678-901234567890
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicListInterviewsResponseDto'
security:
- bearer: []
components:
schemas:
PublicListInterviewsResponseDto:
type: object
properties:
data:
description: Array of interviews
type: array
items:
$ref: '#/components/schemas/PublicInterviewDto'
total:
type: number
description: Total number of items
example: 150
page:
type: number
description: Current page number
example: 1
limit:
type: number
description: Number of items per page
example: 20
totalPages:
type: number
description: Total number of pages
example: 8
required:
- data
- total
- page
- limit
- totalPages
PublicInterviewDto:
type: object
properties:
id:
type: string
format: uuid
description: Interview ID
example: 123e4567-e89b-12d3-a456-426614174000
candidateId:
type: string
format: uuid
description: Candidate ID
example: 987e6543-e21b-12d3-a456-426614174000
agentId:
type: string
description: Agent ID
format: uuid
example: 456e7890-e12b-34d5-a678-901234567890
jobId:
type: string
description: Job ID associated with this interview, if any
format: uuid
nullable: true
example: 123e4567-e89b-12d3-a456-426614174000
status:
type: string
description: Interview status
enum:
- UNDEFINED
- SCHEDULED
- CANCELLED
- FAILED
- COMPLETED
- IN_PROGRESS
example: SCHEDULED
scheduledAt:
type: string
format: date-time
description: Scheduled time
example: '2025-11-20T10:00:00Z'
durationMinutes:
type: number
description: Interview duration in minutes
example: 15
finishedDate:
type: string
format: date-time
description: Finished date
example: '2025-11-20T10:15:00Z'
metadata:
type: object
description: Custom metadata
example:
externalInterviewId: INT-789
callAttempts:
description: >-
Call attempt logs for this interview. Present for phone interviews,
typically empty or undefined for online interviews.
type: array
items:
$ref: '#/components/schemas/PublicCallAttemptDto'
analysis:
description: >-
Candidate analysis data. Present only if analysis has been
generated.
allOf:
- $ref: '#/components/schemas/PublicCandidateAnalysisDto'
createdAt:
type: string
description: Created timestamp
example: '2024-11-16T10:30:00Z'
updatedAt:
type: string
description: Updated timestamp
example: '2024-11-16T10:30:00Z'
isTest:
type: boolean
description: >-
Whether this is a test interview. Test interviews are created with
isTest=true, immediately complete without consuming billing minutes,
and are excluded from billing/usage summaries. Use test interviews
for testing webhook handlers and integration flows.
example: false
required:
- id
- candidateId
- agentId
- status
- scheduledAt
- createdAt
- updatedAt
PublicCallAttemptDto:
type: object
properties:
id:
type: string
description: Call attempt ID
example: c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a
direction:
type: string
description: Interview direction (inbound / outbound)
enum:
- UNDEFINED
- INBOUND
- OUTBOUND
example: OUTBOUND
status:
type: string
description: Current status of the call attempt
enum:
- UNDEFINED
- SCHEDULED
- IN_PROGRESS
- COMPLETED
- NO_ANSWER
- BUSY
- FAILED
- CANCELLED
- VOICEMAIL
- REJECTED
- NO_CONSENT
- TIMEOUT
- MAX_ATTEMPTS_REACHED
- HUMAN_CONTACT_REQUESTED
- OTHER_ROLE_INTEREST
- POLITE_DECLINE
- TIMING_ISSUE
example: COMPLETED
reasonCode:
type: string
description: Machine-readable reason code for failures or special outcomes
example: NO_ANSWER
notes:
type: string
description: Human-readable notes associated with this call attempt
example: Candidate did not pick up, mailbox full
retryNumber:
type: number
description: >-
Retry number for this attempt (starting from 0 or 1 depending on
implementation)
example: 2
recordingUrl:
type: string
description: URL to the call recording, if available
example: https://audio.example.com/recording.mp3
duration:
type: number
description: Duration of the call attempt in seconds
example: 180
scheduledAt:
type: string
format: date-time
description: Scheduled time for this call attempt (ISO 8601, UTC)
example: '2025-07-22T10:00:00Z'
calledAt:
type: string
format: date-time
description: Actual time when the call started (ISO 8601, UTC)
example: '2025-07-22T10:01:00Z'
transcript:
description: >-
Transcript segments for this call attempt, ordered chronologically.
Each segment contains the speaker, text content, and timing. Omitted
when the interview has no transcript or the call attempt did not
produce one.
type: array
items:
$ref: '#/components/schemas/PublicTranscriptSegmentDto'
required:
- id
- direction
PublicCandidateAnalysisDto:
type: object
properties:
id:
type: string
description: Analysis ID
example: 123e4567-e89b-12d3-a456-426614174000
general:
description: General analysis data
allOf:
- $ref: '#/components/schemas/PublicGeneralAnalysisDto'
specific:
type: object
description: >-
Specific analysis data based on interview type (e.g., language test
scores, outreach feedback)
example:
pronunciationScores:
accuracy: 90
fluency: 85
prosody: 82
grammar:
level: C1
required:
- id
- general
PublicTranscriptSegmentDto:
type: object
description: >-
A single segment of a call attempt transcript, representing one
utterance by either the AI interviewer or the candidate.
properties:
speaker:
type: string
description: Who spoke this segment
enum:
- AI
- HUMAN
example: AI
text:
type: string
description: Transcribed text of the utterance
example: Hello, thank you for taking the time to speak with me today.
startTime:
type: number
description: Start time of the segment in seconds from the start of the recording
example: 0
minimum: 0
endTime:
type: number
description: End time of the segment in seconds from the start of the recording
example: 3.5
minimum: 0
language:
type: string
description: BCP-47 language code detected for this segment (e.g. 'en', 'sk')
example: en
pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$
required:
- speaker
- text
- startTime
- endTime
PublicGeneralAnalysisDto:
type: object
properties:
overallRating:
type: number
description: Overall rating (0-100)
example: 85
companyFitRating:
type: string
description: Company fit rating
enum:
- UNDEFINED
- LOW
- MEDIUM
- HIGH
example: HIGH
education:
type: string
description: Summary of education analysis
example: Master's degree in Computer Science
experience:
type: string
description: Summary of experience analysis
example: 5 years of experience in software development
strongPoints:
description: Candidate's strong points and advantages
example:
- Excellent communication skills
- Strong technical expertise in React and Node.js
- Proven track record of leading teams
type: array
items:
type: string
weakPoints:
description: Candidate's weak points or areas for improvement
example:
- Limited experience with microservices
- Needs improvement in system design
type: array
items:
type: string
evaluation:
description: Overall evaluation summary and recommendations
example:
- Strong candidate with relevant experience
- Good cultural fit for the team
- Recommended for next round
type: array
items:
type: string
status:
type: number
description: Analysis processing status
enum:
- 1
- 2
- 3
- 4
example: 3
createdAt:
type: string
description: Created timestamp (UTC)
example: '2024-11-16T10:30:00Z'
format: date-time
updatedAt:
type: string
description: Updated timestamp (UTC)
example: '2024-11-16T10:30:00Z'
format: date-time
required:
- createdAt
- updatedAt
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````