Skip to main content
GET
/
interviews
/
{id}
Get interview by ID
curl --request GET \
  --url https://api.instaview.sk/interviews/{id} \
  --header 'Authorization: Bearer <token>'
{
  "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",
      "transcript": [
        {
          "speaker": "AI",
          "text": "Hello, thank you for taking the time to speak with me today.",
          "startTime": 0,
          "endTime": 3.5,
          "language": "en"
        }
      ]
    }
  ],
  "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,
        "prosody": 82
      },
      "grammar": {
        "level": "C1"
      }
    }
  },
  "isTest": false
}
Retrieves a specific interview by ID, including full details, transcript, analysis, and call attempt information.

​
Overview

The get interview endpoint returns comprehensive information about a single interview, including its current status, transcript, AI analysis (when available), and all associated metadata. This is the primary endpoint for accessing interview results and candidate evaluation data.

​
Use Cases

  • Retrieve Interview Results: Get analysis and transcript after interview completion
  • Check Interview Status: Monitor interview progress in real-time
  • Access Transcripts: Retrieve full conversation transcripts
  • Review Analysis: Access AI-generated candidate evaluation and scores

​
Response Data

The response includes:
  • Interview Details: Status, timestamps, duration, scheduled time
  • Transcript: Full conversation transcript (when available)
  • Analysis: AI-generated evaluation with scores and recommendations
  • Call Attempts: Information about call attempts and recordings
  • Candidate & Agent Info: Associated candidate and agent IDs

​
Analysis Data

When an interview is completed, the response includes comprehensive analysis. The analysis structure contains a general object with overall assessment and an optional specific object for interview-type-specific data: 
{
  "analysis": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "general": {
      "overallRating": 85,
      "companyFitRating": "HIGH",
      "education": "MASTER_LEVEL",
      "experience": "THREE_TO_5_YEARS",
      "strongPoints": ["Strong technical skills", "Clear communication"],
      "weakPoints": ["Limited leadership experience"],
      "evaluation": ["Strong hire for senior individual contributor role"],
      "status": 3,
      "createdAt": "2024-01-20T14:30:00Z",
      "updatedAt": "2024-01-20T14:30:00Z"
    },
    "specific": null
  }
}
The specific field contains interview-type-specific data when available. See the Interviews Resource Guide for details on each interview type.
Analysis data is only available after the interview is completed. For interviews in progress or scheduled, the analysis field will be null.

​
Status Checking

async function checkInterviewStatus(interviewId) {
  const response = await fetch(
    `https://api.instaview.sk/interviews/${interviewId}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );

  const { data } = await response.json();

  return {
    status: data.status,
    hasAnalysis: data.analysis !== null,
    durationMinutes: data.durationMinutes,
    finishedDate: data.finishedDate,
  };
}

​
Company Isolation

The API ensures that you can only access interviews that belong to candidates in your company. Attempting to access an interview from another company will result in a 403 Forbidden error.

​
Error Scenarios

  • 404 Not Found: Interview doesn’t exist or has been deleted
  • 403 Forbidden: Interview belongs to a different company

Interviews Resource Guide

Learn about interview management and analysis structure

List Interviews

List all interviews for a candidate

Create Interview

Schedule new interviews

Get Analysis PDF

Download the analysis PDF report

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

​
id
string<uuid>
required

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
​
id
string<uuid>
required

Interview ID

Example:

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

​
candidateId
string<uuid>
required

Candidate ID

Example:

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

​
agentId
string<uuid>
required

Agent ID

Example:

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

​
status
enum<string>
required

Interview status

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

"SCHEDULED"

​
scheduledAt
string<date-time>
required

Scheduled time

Example:

"2025-11-20T10:00:00Z"

​
createdAt
string
required

Created timestamp

Example:

"2024-11-16T10:30:00Z"

​
updatedAt
string
required

Updated timestamp

Example:

"2024-11-16T10:30:00Z"

​
jobId
string<uuid> | null

Job ID associated with this interview, if any

Example:

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

​
durationMinutes
number

Interview duration in minutes

Example:

15

​
finishedDate
string<date-time>

Finished date

Example:

"2025-11-20T10:15:00Z"

​
metadata
object

Custom metadata

Example:
{ "externalInterviewId": "INT-789" }
​
callAttempts
object[]

Call attempt logs for this interview. Present for phone interviews, typically empty or undefined for online interviews.

​
analysis
object

Candidate analysis data. Present only if analysis has been generated.

​
isTest
boolean

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