Skip to main content
GET
/
interviews
List interviews
curl --request GET \
  --url https://api.instaview.sk/interviews \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "candidateId": "987e6543-e21b-12d3-a456-426614174000",
      "agentId": "456e7890-e12b-34d5-a678-901234567890",
      "status": "SCHEDULED",
      "scheduledAt": "2025-11-20T10:00:00Z",
      "createdAt": "2024-11-16T10:30:00Z",
      "updatedAt": "2024-11-16T10:30:00Z",
      "jobId": "123e4567-e89b-12d3-a456-426614174000",
      "durationMinutes": 15,
      "finishedDate": "2025-11-20T10:15:00Z",
      "metadata": {
        "externalInterviewId": "INT-789"
      },
      "callAttempts": [
        {
          "id": "c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a",
          "direction": "OUTBOUND",
          "status": "COMPLETED",
          "reasonCode": "NO_ANSWER",
          "notes": "Candidate did not pick up, mailbox full",
          "retryNumber": 2,
          "recordingUrl": "https://audio.example.com/recording.mp3",
          "duration": 180,
          "scheduledAt": "2025-07-22T10:00:00Z",
          "calledAt": "2025-07-22T10:01:00Z"
        }
      ],
      "analysis": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "general": {
          "createdAt": "2024-11-16T10:30:00Z",
          "updatedAt": "2024-11-16T10:30:00Z",
          "overallRating": 85,
          "companyFitRating": "HIGH",
          "education": "Master's degree in Computer Science",
          "experience": "5 years of experience in software development",
          "strongPoints": [
            "Excellent communication skills",
            "Strong technical expertise in React and Node.js",
            "Proven track record of leading teams"
          ],
          "weakPoints": [
            "Limited experience with microservices",
            "Needs improvement in system design"
          ],
          "evaluation": [
            "Strong candidate with relevant experience",
            "Good cultural fit for the team",
            "Recommended for next round"
          ],
          "status": 3
        },
        "specific": {
          "pronunciationScores": {
            "accuracy": 90,
            "fluency": 85
          },
          "grammar": {
            "level": "C1"
          }
        }
      },
      "isTest": false
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}
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

// List all interviews for a candidate
GET /interviews?candidateId=candidate-uuid

​
With Pagination

// 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): 
// Get only completed interviews
GET /interviews?candidateId=candidate-uuid&status=completed

​
Response Structure

The response includes interview details along with analysis data (when available): 
{
  "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

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.

Interviews Resource Guide

Learn about interview management and analysis

Get Interview

Retrieve a specific interview by ID

Pagination Guide

Understand pagination best practices

Candidates Resource Guide

Manage candidate profiles

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
page
integer
default:1

Page number (1-based)

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

1

​
limit
integer
default:20

Number of items per page

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

20

​
companyId
string<uuid>

Company ID (required for ATS keys, optional for regular keys)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
candidateId
string<uuid>
required

Filter by candidate ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
agentId
string<uuid>

Filter by agent ID

Example:

"987e6543-e21b-12d3-a456-426614174000"

​
status
enum<string>

Filter by interview status

Available options:
UNDEFINED,
SCHEDULED,
CANCELLED,
FAILED,
COMPLETED,
IN_PROGRESS
Example:

"SCHEDULED"

​
jobId
string

[Deprecated] Filter by job ID (through candidate). Redundant when candidateId is required.

Example:

"456e7890-e12b-34d5-a678-901234567890"

Response

200 - application/json
​
data
object[]
required

Array of interviews

​
total
number
required

Total number of items

Example:

150

​
page
number
required

Current page number

Example:

1

​
limit
number
required

Number of items per page

Example:

20

​
totalPages
number
required

Total number of pages

Example:

8