Create Interview - InstaView API

Create interview

curl --request POST \
  --url https://api.instaview.sk/interviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "candidateId": "123e4567-e89b-12d3-a456-426614174000",
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "agentId": "987e6543-e21b-12d3-a456-426614174000",
  "scheduleTime": "2025-11-20T10:00:00Z",
  "agent": {
    "type": "ONLINE",
    "name": "Senior Developer Interview",
    "language": "EN",
    "duration": 30,
    "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
    "focus": "SCREENING",
    "questions": [
      "What is your experience with React?",
      "Tell me about a challenging project you worked on"
    ],
    "instructions": "Focus on technical skills and previous project experience",
    "cefrLevel": "B1",
    "contextConfig": {
      "role": "an account executive for Acme",
      "communicationStyle": "concise and direct",
      "callToAction": "book a 30-minute demo"
    },
    "analyticsConfig": {
      "extractionTargets": [
        {
          "label": "Budget confirmed",
          "type": "bool",
          "key": "budget_confirmed",
          "enumValues": [
            "hot",
            "warm",
            "cold"
          ],
          "ideal": "A confirmed budget of at least 10k",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "scoringCriteria": [
        {
          "label": "Handled objections",
          "description": "Acknowledged the objection and answered it with a concrete example",
          "key": "handled_objections",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "outcomes": [
        {
          "label": "Meeting booked",
          "description": "The contact agreed to a specific date and time",
          "key": "meeting_booked"
        }
      ],
      "outputTags": [
        {
          "label": "Needs follow-up",
          "key": "needs_followup",
          "description": "The contact asked to be called back"
        }
      ],
      "capture": {
        "recording": true,
        "transcript": true,
        "summary": true,
        "qa": true,
        "evaluation": true,
        "sentiment": true
      }
    },
    "overrides": {
      "companyName": "Acme Manufacturing",
      "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
    }
  },
  "metadata": {
    "externalInterviewId": "INT-789",
    "interviewerNotes": "Focus on technical skills"
  },
  "isTest": false
}
'

import requests

url = "https://api.instaview.sk/interviews"

payload = {
    "candidateId": "123e4567-e89b-12d3-a456-426614174000",
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "agentId": "987e6543-e21b-12d3-a456-426614174000",
    "scheduleTime": "2025-11-20T10:00:00Z",
    "agent": {
        "type": "ONLINE",
        "name": "Senior Developer Interview",
        "language": "EN",
        "duration": 30,
        "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
        "focus": "SCREENING",
        "questions": ["What is your experience with React?", "Tell me about a challenging project you worked on"],
        "instructions": "Focus on technical skills and previous project experience",
        "cefrLevel": "B1",
        "contextConfig": {
            "role": "an account executive for Acme",
            "communicationStyle": "concise and direct",
            "callToAction": "book a 30-minute demo"
        },
        "analyticsConfig": {
            "extractionTargets": [
                {
                    "label": "Budget confirmed",
                    "type": "bool",
                    "key": "budget_confirmed",
                    "enumValues": ["hot", "warm", "cold"],
                    "ideal": "A confirmed budget of at least 10k",
                    "importance": "PREFERRED",
                    "weight": 40
                }
            ],
            "scoringCriteria": [
                {
                    "label": "Handled objections",
                    "description": "Acknowledged the objection and answered it with a concrete example",
                    "key": "handled_objections",
                    "importance": "PREFERRED",
                    "weight": 40
                }
            ],
            "outcomes": [
                {
                    "label": "Meeting booked",
                    "description": "The contact agreed to a specific date and time",
                    "key": "meeting_booked"
                }
            ],
            "outputTags": [
                {
                    "label": "Needs follow-up",
                    "key": "needs_followup",
                    "description": "The contact asked to be called back"
                }
            ],
            "capture": {
                "recording": True,
                "transcript": True,
                "summary": True,
                "qa": True,
                "evaluation": True,
                "sentiment": True
            }
        },
        "overrides": {
            "companyName": "Acme Manufacturing",
            "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
        }
    },
    "metadata": {
        "externalInterviewId": "INT-789",
        "interviewerNotes": "Focus on technical skills"
    },
    "isTest": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    candidateId: '123e4567-e89b-12d3-a456-426614174000',
    jobId: '123e4567-e89b-12d3-a456-426614174000',
    agentId: '987e6543-e21b-12d3-a456-426614174000',
    scheduleTime: '2025-11-20T10:00:00Z',
    agent: {
      type: 'ONLINE',
      name: 'Senior Developer Interview',
      language: 'EN',
      duration: 30,
      companyPhoneNumberId: '123e4567-e89b-12d3-a456-426614174000',
      focus: 'SCREENING',
      questions: [
        'What is your experience with React?',
        'Tell me about a challenging project you worked on'
      ],
      instructions: 'Focus on technical skills and previous project experience',
      cefrLevel: 'B1',
      contextConfig: {
        role: 'an account executive for Acme',
        communicationStyle: 'concise and direct',
        callToAction: 'book a 30-minute demo'
      },
      analyticsConfig: {
        extractionTargets: [
          {
            label: 'Budget confirmed',
            type: 'bool',
            key: 'budget_confirmed',
            enumValues: ['hot', 'warm', 'cold'],
            ideal: 'A confirmed budget of at least 10k',
            importance: 'PREFERRED',
            weight: 40
          }
        ],
        scoringCriteria: [
          {
            label: 'Handled objections',
            description: 'Acknowledged the objection and answered it with a concrete example',
            key: 'handled_objections',
            importance: 'PREFERRED',
            weight: 40
          }
        ],
        outcomes: [
          {
            label: 'Meeting booked',
            description: 'The contact agreed to a specific date and time',
            key: 'meeting_booked'
          }
        ],
        outputTags: [
          {
            label: 'Needs follow-up',
            key: 'needs_followup',
            description: 'The contact asked to be called back'
          }
        ],
        capture: {
          recording: true,
          transcript: true,
          summary: true,
          qa: true,
          evaluation: true,
          sentiment: true
        }
      },
      overrides: {
        companyName: 'Acme Manufacturing',
        companyDescription: 'Acme makes industrial fasteners and employs 400 people across Slovakia.'
      }
    },
    metadata: {externalInterviewId: 'INT-789', interviewerNotes: 'Focus on technical skills'},
    isTest: false
  })
};

fetch('https://api.instaview.sk/interviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instaview.sk/interviews",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'candidateId' => '123e4567-e89b-12d3-a456-426614174000',
    'jobId' => '123e4567-e89b-12d3-a456-426614174000',
    'agentId' => '987e6543-e21b-12d3-a456-426614174000',
    'scheduleTime' => '2025-11-20T10:00:00Z',
    'agent' => [
        'type' => 'ONLINE',
        'name' => 'Senior Developer Interview',
        'language' => 'EN',
        'duration' => 30,
        'companyPhoneNumberId' => '123e4567-e89b-12d3-a456-426614174000',
        'focus' => 'SCREENING',
        'questions' => [
                'What is your experience with React?',
                'Tell me about a challenging project you worked on'
        ],
        'instructions' => 'Focus on technical skills and previous project experience',
        'cefrLevel' => 'B1',
        'contextConfig' => [
                'role' => 'an account executive for Acme',
                'communicationStyle' => 'concise and direct',
                'callToAction' => 'book a 30-minute demo'
        ],
        'analyticsConfig' => [
                'extractionTargets' => [
                                [
                                                                'label' => 'Budget confirmed',
                                                                'type' => 'bool',
                                                                'key' => 'budget_confirmed',
                                                                'enumValues' => [
                                                                                                                                'hot',
                                                                                                                                'warm',
                                                                                                                                'cold'
                                                                ],
                                                                'ideal' => 'A confirmed budget of at least 10k',
                                                                'importance' => 'PREFERRED',
                                                                'weight' => 40
                                ]
                ],
                'scoringCriteria' => [
                                [
                                                                'label' => 'Handled objections',
                                                                'description' => 'Acknowledged the objection and answered it with a concrete example',
                                                                'key' => 'handled_objections',
                                                                'importance' => 'PREFERRED',
                                                                'weight' => 40
                                ]
                ],
                'outcomes' => [
                                [
                                                                'label' => 'Meeting booked',
                                                                'description' => 'The contact agreed to a specific date and time',
                                                                'key' => 'meeting_booked'
                                ]
                ],
                'outputTags' => [
                                [
                                                                'label' => 'Needs follow-up',
                                                                'key' => 'needs_followup',
                                                                'description' => 'The contact asked to be called back'
                                ]
                ],
                'capture' => [
                                'recording' => true,
                                'transcript' => true,
                                'summary' => true,
                                'qa' => true,
                                'evaluation' => true,
                                'sentiment' => true
                ]
        ],
        'overrides' => [
                'companyName' => 'Acme Manufacturing',
                'companyDescription' => 'Acme makes industrial fasteners and employs 400 people across Slovakia.'
        ]
    ],
    'metadata' => [
        'externalInterviewId' => 'INT-789',
        'interviewerNotes' => 'Focus on technical skills'
    ],
    'isTest' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instaview.sk/interviews"

	payload := strings.NewReader("{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instaview.sk/interviews")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/interviews")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
      }
    }
  },
  "analytics": {
    "matchScore": 72,
    "updatedAt": "2026-08-03T10:30:00Z",
    "fields": [
      {
        "key": "budget_confirmed",
        "label": "Budget confirmed",
        "value": true,
        "confidence": 0.5,
        "evidence": "Said they have signed off on 15k for this quarter"
      }
    ],
    "scoring": {
      "total": 72,
      "items": [
        {
          "key": "budget_confirmed",
          "kind": "field",
          "label": "Budget confirmed",
          "score": 80,
          "weightPercent": 33.3,
          "reasoning": "<string>"
        }
      ]
    },
    "outcomes": [
      {
        "key": "meeting_booked",
        "label": "Meeting booked",
        "met": true,
        "confidence": 0.5,
        "evidence": "<string>"
      }
    ],
    "tags": [
      {
        "key": "needs_followup",
        "label": "Needs follow-up",
        "applied": true,
        "reason": "<string>"
      }
    ],
    "qa": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "question": "<string>",
        "answered": true,
        "answer": "<string>",
        "evidence": "<string>"
      }
    ],
    "evaluation": {
      "strengths": [
        "<string>"
      ],
      "concerns": [
        "<string>"
      ],
      "objections": [
        "<string>"
      ],
      "assessment": [
        "<string>"
      ]
    },
    "sentiment": {
      "overall": "positive",
      "score": 0.5,
      "notes": "<string>"
    },
    "summary": "Qualified lead; demo booked for Thursday."
  },
  "isTest": false
}

POST

interviews

Create interview

curl --request POST \
  --url https://api.instaview.sk/interviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "candidateId": "123e4567-e89b-12d3-a456-426614174000",
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "agentId": "987e6543-e21b-12d3-a456-426614174000",
  "scheduleTime": "2025-11-20T10:00:00Z",
  "agent": {
    "type": "ONLINE",
    "name": "Senior Developer Interview",
    "language": "EN",
    "duration": 30,
    "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
    "focus": "SCREENING",
    "questions": [
      "What is your experience with React?",
      "Tell me about a challenging project you worked on"
    ],
    "instructions": "Focus on technical skills and previous project experience",
    "cefrLevel": "B1",
    "contextConfig": {
      "role": "an account executive for Acme",
      "communicationStyle": "concise and direct",
      "callToAction": "book a 30-minute demo"
    },
    "analyticsConfig": {
      "extractionTargets": [
        {
          "label": "Budget confirmed",
          "type": "bool",
          "key": "budget_confirmed",
          "enumValues": [
            "hot",
            "warm",
            "cold"
          ],
          "ideal": "A confirmed budget of at least 10k",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "scoringCriteria": [
        {
          "label": "Handled objections",
          "description": "Acknowledged the objection and answered it with a concrete example",
          "key": "handled_objections",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "outcomes": [
        {
          "label": "Meeting booked",
          "description": "The contact agreed to a specific date and time",
          "key": "meeting_booked"
        }
      ],
      "outputTags": [
        {
          "label": "Needs follow-up",
          "key": "needs_followup",
          "description": "The contact asked to be called back"
        }
      ],
      "capture": {
        "recording": true,
        "transcript": true,
        "summary": true,
        "qa": true,
        "evaluation": true,
        "sentiment": true
      }
    },
    "overrides": {
      "companyName": "Acme Manufacturing",
      "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
    }
  },
  "metadata": {
    "externalInterviewId": "INT-789",
    "interviewerNotes": "Focus on technical skills"
  },
  "isTest": false
}
'

import requests

url = "https://api.instaview.sk/interviews"

payload = {
    "candidateId": "123e4567-e89b-12d3-a456-426614174000",
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "agentId": "987e6543-e21b-12d3-a456-426614174000",
    "scheduleTime": "2025-11-20T10:00:00Z",
    "agent": {
        "type": "ONLINE",
        "name": "Senior Developer Interview",
        "language": "EN",
        "duration": 30,
        "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
        "focus": "SCREENING",
        "questions": ["What is your experience with React?", "Tell me about a challenging project you worked on"],
        "instructions": "Focus on technical skills and previous project experience",
        "cefrLevel": "B1",
        "contextConfig": {
            "role": "an account executive for Acme",
            "communicationStyle": "concise and direct",
            "callToAction": "book a 30-minute demo"
        },
        "analyticsConfig": {
            "extractionTargets": [
                {
                    "label": "Budget confirmed",
                    "type": "bool",
                    "key": "budget_confirmed",
                    "enumValues": ["hot", "warm", "cold"],
                    "ideal": "A confirmed budget of at least 10k",
                    "importance": "PREFERRED",
                    "weight": 40
                }
            ],
            "scoringCriteria": [
                {
                    "label": "Handled objections",
                    "description": "Acknowledged the objection and answered it with a concrete example",
                    "key": "handled_objections",
                    "importance": "PREFERRED",
                    "weight": 40
                }
            ],
            "outcomes": [
                {
                    "label": "Meeting booked",
                    "description": "The contact agreed to a specific date and time",
                    "key": "meeting_booked"
                }
            ],
            "outputTags": [
                {
                    "label": "Needs follow-up",
                    "key": "needs_followup",
                    "description": "The contact asked to be called back"
                }
            ],
            "capture": {
                "recording": True,
                "transcript": True,
                "summary": True,
                "qa": True,
                "evaluation": True,
                "sentiment": True
            }
        },
        "overrides": {
            "companyName": "Acme Manufacturing",
            "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
        }
    },
    "metadata": {
        "externalInterviewId": "INT-789",
        "interviewerNotes": "Focus on technical skills"
    },
    "isTest": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    candidateId: '123e4567-e89b-12d3-a456-426614174000',
    jobId: '123e4567-e89b-12d3-a456-426614174000',
    agentId: '987e6543-e21b-12d3-a456-426614174000',
    scheduleTime: '2025-11-20T10:00:00Z',
    agent: {
      type: 'ONLINE',
      name: 'Senior Developer Interview',
      language: 'EN',
      duration: 30,
      companyPhoneNumberId: '123e4567-e89b-12d3-a456-426614174000',
      focus: 'SCREENING',
      questions: [
        'What is your experience with React?',
        'Tell me about a challenging project you worked on'
      ],
      instructions: 'Focus on technical skills and previous project experience',
      cefrLevel: 'B1',
      contextConfig: {
        role: 'an account executive for Acme',
        communicationStyle: 'concise and direct',
        callToAction: 'book a 30-minute demo'
      },
      analyticsConfig: {
        extractionTargets: [
          {
            label: 'Budget confirmed',
            type: 'bool',
            key: 'budget_confirmed',
            enumValues: ['hot', 'warm', 'cold'],
            ideal: 'A confirmed budget of at least 10k',
            importance: 'PREFERRED',
            weight: 40
          }
        ],
        scoringCriteria: [
          {
            label: 'Handled objections',
            description: 'Acknowledged the objection and answered it with a concrete example',
            key: 'handled_objections',
            importance: 'PREFERRED',
            weight: 40
          }
        ],
        outcomes: [
          {
            label: 'Meeting booked',
            description: 'The contact agreed to a specific date and time',
            key: 'meeting_booked'
          }
        ],
        outputTags: [
          {
            label: 'Needs follow-up',
            key: 'needs_followup',
            description: 'The contact asked to be called back'
          }
        ],
        capture: {
          recording: true,
          transcript: true,
          summary: true,
          qa: true,
          evaluation: true,
          sentiment: true
        }
      },
      overrides: {
        companyName: 'Acme Manufacturing',
        companyDescription: 'Acme makes industrial fasteners and employs 400 people across Slovakia.'
      }
    },
    metadata: {externalInterviewId: 'INT-789', interviewerNotes: 'Focus on technical skills'},
    isTest: false
  })
};

fetch('https://api.instaview.sk/interviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instaview.sk/interviews",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'candidateId' => '123e4567-e89b-12d3-a456-426614174000',
    'jobId' => '123e4567-e89b-12d3-a456-426614174000',
    'agentId' => '987e6543-e21b-12d3-a456-426614174000',
    'scheduleTime' => '2025-11-20T10:00:00Z',
    'agent' => [
        'type' => 'ONLINE',
        'name' => 'Senior Developer Interview',
        'language' => 'EN',
        'duration' => 30,
        'companyPhoneNumberId' => '123e4567-e89b-12d3-a456-426614174000',
        'focus' => 'SCREENING',
        'questions' => [
                'What is your experience with React?',
                'Tell me about a challenging project you worked on'
        ],
        'instructions' => 'Focus on technical skills and previous project experience',
        'cefrLevel' => 'B1',
        'contextConfig' => [
                'role' => 'an account executive for Acme',
                'communicationStyle' => 'concise and direct',
                'callToAction' => 'book a 30-minute demo'
        ],
        'analyticsConfig' => [
                'extractionTargets' => [
                                [
                                                                'label' => 'Budget confirmed',
                                                                'type' => 'bool',
                                                                'key' => 'budget_confirmed',
                                                                'enumValues' => [
                                                                                                                                'hot',
                                                                                                                                'warm',
                                                                                                                                'cold'
                                                                ],
                                                                'ideal' => 'A confirmed budget of at least 10k',
                                                                'importance' => 'PREFERRED',
                                                                'weight' => 40
                                ]
                ],
                'scoringCriteria' => [
                                [
                                                                'label' => 'Handled objections',
                                                                'description' => 'Acknowledged the objection and answered it with a concrete example',
                                                                'key' => 'handled_objections',
                                                                'importance' => 'PREFERRED',
                                                                'weight' => 40
                                ]
                ],
                'outcomes' => [
                                [
                                                                'label' => 'Meeting booked',
                                                                'description' => 'The contact agreed to a specific date and time',
                                                                'key' => 'meeting_booked'
                                ]
                ],
                'outputTags' => [
                                [
                                                                'label' => 'Needs follow-up',
                                                                'key' => 'needs_followup',
                                                                'description' => 'The contact asked to be called back'
                                ]
                ],
                'capture' => [
                                'recording' => true,
                                'transcript' => true,
                                'summary' => true,
                                'qa' => true,
                                'evaluation' => true,
                                'sentiment' => true
                ]
        ],
        'overrides' => [
                'companyName' => 'Acme Manufacturing',
                'companyDescription' => 'Acme makes industrial fasteners and employs 400 people across Slovakia.'
        ]
    ],
    'metadata' => [
        'externalInterviewId' => 'INT-789',
        'interviewerNotes' => 'Focus on technical skills'
    ],
    'isTest' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instaview.sk/interviews"

	payload := strings.NewReader("{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instaview.sk/interviews")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/interviews")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"candidateId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"jobId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agentId\": \"987e6543-e21b-12d3-a456-426614174000\",\n  \"scheduleTime\": \"2025-11-20T10:00:00Z\",\n  \"agent\": {\n    \"type\": \"ONLINE\",\n    \"name\": \"Senior Developer Interview\",\n    \"language\": \"EN\",\n    \"duration\": 30,\n    \"companyPhoneNumberId\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"focus\": \"SCREENING\",\n    \"questions\": [\n      \"What is your experience with React?\",\n      \"Tell me about a challenging project you worked on\"\n    ],\n    \"instructions\": \"Focus on technical skills and previous project experience\",\n    \"cefrLevel\": \"B1\",\n    \"contextConfig\": {\n      \"role\": \"an account executive for Acme\",\n      \"communicationStyle\": \"concise and direct\",\n      \"callToAction\": \"book a 30-minute demo\"\n    },\n    \"analyticsConfig\": {\n      \"extractionTargets\": [\n        {\n          \"label\": \"Budget confirmed\",\n          \"type\": \"bool\",\n          \"key\": \"budget_confirmed\",\n          \"enumValues\": [\n            \"hot\",\n            \"warm\",\n            \"cold\"\n          ],\n          \"ideal\": \"A confirmed budget of at least 10k\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"scoringCriteria\": [\n        {\n          \"label\": \"Handled objections\",\n          \"description\": \"Acknowledged the objection and answered it with a concrete example\",\n          \"key\": \"handled_objections\",\n          \"importance\": \"PREFERRED\",\n          \"weight\": 40\n        }\n      ],\n      \"outcomes\": [\n        {\n          \"label\": \"Meeting booked\",\n          \"description\": \"The contact agreed to a specific date and time\",\n          \"key\": \"meeting_booked\"\n        }\n      ],\n      \"outputTags\": [\n        {\n          \"label\": \"Needs follow-up\",\n          \"key\": \"needs_followup\",\n          \"description\": \"The contact asked to be called back\"\n        }\n      ],\n      \"capture\": {\n        \"recording\": true,\n        \"transcript\": true,\n        \"summary\": true,\n        \"qa\": true,\n        \"evaluation\": true,\n        \"sentiment\": true\n      }\n    },\n    \"overrides\": {\n      \"companyName\": \"Acme Manufacturing\",\n      \"companyDescription\": \"Acme makes industrial fasteners and employs 400 people across Slovakia.\"\n    }\n  },\n  \"metadata\": {\n    \"externalInterviewId\": \"INT-789\",\n    \"interviewerNotes\": \"Focus on technical skills\"\n  },\n  \"isTest\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
      }
    }
  },
  "analytics": {
    "matchScore": 72,
    "updatedAt": "2026-08-03T10:30:00Z",
    "fields": [
      {
        "key": "budget_confirmed",
        "label": "Budget confirmed",
        "value": true,
        "confidence": 0.5,
        "evidence": "Said they have signed off on 15k for this quarter"
      }
    ],
    "scoring": {
      "total": 72,
      "items": [
        {
          "key": "budget_confirmed",
          "kind": "field",
          "label": "Budget confirmed",
          "score": 80,
          "weightPercent": 33.3,
          "reasoning": "<string>"
        }
      ]
    },
    "outcomes": [
      {
        "key": "meeting_booked",
        "label": "Meeting booked",
        "met": true,
        "confidence": 0.5,
        "evidence": "<string>"
      }
    ],
    "tags": [
      {
        "key": "needs_followup",
        "label": "Needs follow-up",
        "applied": true,
        "reason": "<string>"
      }
    ],
    "qa": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "question": "<string>",
        "answered": true,
        "answer": "<string>",
        "evidence": "<string>"
      }
    ],
    "evaluation": {
      "strengths": [
        "<string>"
      ],
      "concerns": [
        "<string>"
      ],
      "objections": [
        "<string>"
      ],
      "assessment": [
        "<string>"
      ]
    },
    "sentiment": {
      "overall": "positive",
      "score": 0.5,
      "notes": "<string>"
    },
    "summary": "Qualified lead; demo booked for Thursday."
  },
  "isTest": false
}

Creates a new AI-powered interview session for a candidate. This endpoint supports both existing candidates/agents and inline resource creation, making it flexible for various integration scenarios.

Overview

The create interview endpoint allows you to schedule AI-powered interviews with candidates. You can use existing candidate and agent IDs, or create them on-the-fly using inline definitions. Interviews can be scheduled for a future time or started immediately.

Use Cases

Scheduled Interviews: Schedule interviews for a specific date and time
Immediate Interviews: Start interviews right away for quick screening
Inline Resources: Create interviews without pre-creating candidates or agents
Bulk Interview Scheduling: Automate interview scheduling for multiple candidates

Inline Candidate, Agent, and Job Support

You can create interviews with candidates, agents, and jobs that don’t exist yet by providing inline resource objects. This enables streamlined interview scheduling without pre-creating resources in your system.

Inline Candidate with Job Association

{
  "candidate": {
    "jobId": "job-uuid",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+1234567890",
    "gdprExpiryDate": "2026-11-16",
    "workHistory": [
      {
        "companyName": "Tech Corp",
        "candidatePosition": "Software Engineer",
        "referenceName": "Jane Smith",
        "referencePhone": "+1234567890",
        "startDate": "2020-01-01",
        "endDate": "2022-12-31"
      }
    ]
  },
  "agentId": "existing-agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Inline Candidate with Inline Job

Create both the candidate and job inline for a completely self-contained interview creation:

{
  "candidate": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+1234567890",
    "gdprExpiryDate": "2026-11-16"
  },
  "job": {
    "jobTitle": "Senior Backend Engineer",
    "jobDescription": "We are looking for a senior engineer...",
    "requiredSkills": ["TypeScript", "NestJS", "PostgreSQL"],
    "niceToHaveSkills": ["Redis", "AWS"],
    "languages": ["EN"],
    "experience": "SENIOR",
    "contractType": "FULL_TIME"
  },
  "agentId": "existing-agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Complete Inline Workflow: When using candidate with job: - A new Job entity is created in your company - A new Candidate entity is created and automatically associated with the new job

The Interview is linked to both the new candidate and job - All resources become permanent entities in your system - This is the most streamlined way to schedule interviews without any pre-existing resources

Inline Candidate without Job Association

{
  "candidate": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+1234567890",
    "gdprExpiryDate": "2026-11-16"
  },
  "agentId": "existing-agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Job Specification Options: You can specify the job in several ways: - Create inline: Use job at the DTO level to create a new job - Reference existing: Use jobId at the DTO level to link to an existing job - Within inline candidate: Use jobId inside candidate for a more compact syntax when creating both candidate and job association - No job: Omit all job fields to create a candidate in your talent pool without job association (can be assigned later via the update candidate endpoint) Priority: When multiple job sources are provided, job takes precedence over DTO-level jobId, which takes precedence over candidate.jobId. XOR Validation: You cannot combine candidate.jobId with DTO-level job fields (jobId or job) as this would be ambiguous. Choose one method per request.

Inline Custom Agent

The inline agent accepts the same custom-agent fields as Create Agent: send a flow (optionally with guardrails, contextConfig and analyticsConfig) and the agent is created as a custom agent, running the conversation you designed instead of a template. As there, focus must be omitted when a flow is present, ids and schemaVersion are assigned by InstaView, and an invalid flow is rejected with a 422 carrying the same errors array — every problem found, each with the path of the block it is on. No interview is created when that happens. Sending analyticsConfig here is how a one-off call returns structured data rather than just a transcript — the results come back as analytics on this interview and on its analysis.completed webhook.

{
  "candidate": {
    "firstName": "Jana",
    "lastName": "Novák",
    "phoneNumber": "+421900123456",
    "gdprExpiryDate": "2027-08-02"
  },
  "agent": {
    "name": "Renewal check-in",
    "type": "PHONE",
    "language": "EN",
    "duration": 10,
    "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
    "flow": {
      "firstMessage": { "type": "first_message", "text": "Hi {{contact.first_name}}, quick question about your renewal." },
      "sections": [{ "type": "sequential", "prompt": "Ask whether they intend to renew, and note any blockers." }],
      "lastMessage": { "type": "last_message", "text": "Thanks — we'll follow up by email." }
    },
    "analyticsConfig": {
      "extractionTargets": [
        { "key": "intends_to_renew", "label": "Intends to renew", "type": "bool" }
      ],
      "outcomes": [
        { "label": "Renewal confirmed", "description": "The contact committed to renewing" }
      ]
    }
  }
}

Inline creation mints a permanent agent per interview. That is fine for a one-off, but calling a list of 50 people this way leaves 50 near-identical custom agents behind. When the same flow will call more than one person, create the agent once via POST /agents and pass agentId.

Generic Focus and Jobless Interviews

Two focuses are job-optional — they can interview someone without associating the interview with a job: GENERIC, and any custom agent (one created with a flow). Every other focus requires a job. The two are not identical, and the difference is worth knowing:

	`GENERIC`	Custom (flow-based)
Interview without a job	Yes, always	Yes, always
Candidate may hold job assignments	Yes, any number	Yes, any number
`jobId` needed for a multi-job candidate	No	No
May you attach a job anyway	Yes, optional	No — `400`

A job-optional focus ignores the candidate’s assignments entirely. You do not need to pick one with jobId, and a candidate assigned to five jobs is interviewed exactly like one assigned to none. The “specify a jobId” error described under Candidate with Multiple Jobs applies only to job-requiring focuses.

Custom agents are always jobless. An agent created with a flow is job-agnostic by design: its prompt comes entirely from the flow, so a job would never be read. This is stricter than GENERIC, which merely makes a job optional — sending job, jobId or candidate.jobId for a custom agent is a 400 rather than a silently ignored field.

Generic focus agents are designed for interviews where candidates don’t need to be assigned to a specific job. This is useful for:

Talent Pool Building: Interviewing candidates for future opportunities without a specific role
General Outreach: Engaging with candidates in your database who aren’t currently assigned to jobs
Pre-screening: Conducting initial conversations before matching candidates to specific positions

Creating a Jobless Interview with GENERIC Focus

{
  "candidate": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+1234567890",
    "gdprExpiryDate": "2026-11-16"
    // No jobId - a GENERIC interview does not need one
  },
  "agentId": "generic-agent-uuid", // Agent with focus: "GENERIC"
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Validation: The API will return a 400 Bad Request error if:

You try to create a jobless interview (no job specified) with an agent whose focus requires a job — that is, anything other than GENERIC or a custom agent
You attach a job to a custom agent’s interview

Note that a GENERIC interview is not rejected for a candidate who has job assignments: the assignments are simply not used.For more details on Generic interview analysis structure, see the Interviews Resource Guide.

Existing Candidate with Inline Job

You can also define the job inline using job when you already have a candidate but don’t want to create a separate job resource first.

{
  "candidateId": "candidate-uuid",
  "job": {
    "jobTitle": "Senior Backend Engineer",
    "jobDescription": "We are looking for a senior engineer...",
    "jobUrl": "https://company.com/jobs/123",
    "benefits": "Health insurance, remote work",
    "requiredSkills": ["TypeScript", "NestJS", "PostgreSQL"],
    "niceToHaveSkills": ["Redis", "AWS"],
    "languages": ["EN"],
    "languageRequirements": [
      { "language": "EN", "proficiency": "C1" }
    ],
    "education": ["BACHELORS"],
    "experience": "SENIOR",
    "otherRequirements": "Comfortable with async communication",
    "contractType": "FULL_TIME",
    "location": {
      "workMode": "REMOTE",
      "street": "Main Street 1",
      "city": "Bratislava",
      "postalCode": "81101",
      "countryCode": "SK"
    },
    "salary": {
      "min": 4000,
      "max": 5500,
      "currency": "EUR",
      "period": "MONTHLY"
    },
    "humanRecruiter": "John Doe",
    "metadata": {
      "externalJobId": "JOB-12345",
      "department": "Engineering"
    }
  },
  "agentId": "existing-agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Inline Job Behavior: - When you provide job together with an existing candidateId, the API: - Creates a full Job entity in your company using the inline fields. - Automatically associates the candidate with the new job if they weren’t already linked. - Links the interview to this newly created job. - jobId and job are mutually exclusive (XOR): - Use either jobId (existing job) or job (inline job definition), but not both.

Billing and Limits

Creating interviews consumes interview minutes from your company’s billing plan. Ensure you have sufficient minutes available before scheduling bulk interviews. The API will return a 403 Forbidden error if billing limits are exceeded.Exception: Test interviews (created with isTest: true) do not consume billing minutes and bypass all billing checks.

Scheduling Options

Immediate Interview

Omit scheduleTime to start the interview immediately:

{
  "candidateId": "candidate-uuid",
  "agentId": "agent-uuid"
}

Scheduled Interview

Provide a future scheduleTime timestamp (max 30 days in the future):

{
  "candidateId": "candidate-uuid",
  "agentId": "agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Note: When using existing candidates, ensure they already exist in your system. For inline candidates, all required fields (firstName, lastName, email or phoneNumber, gdprExpiryDate) must be provided.

Job Selection for Existing Candidates

When using an existing candidateId, you can optionally specify a jobId to indicate which job the interview is for. This is especially important when a candidate is associated with multiple jobs.

Candidate with Single Job

If the candidate has only one job (or no jobs), the jobId field is optional. The system will automatically use the candidate’s first job if available:

{
  "candidateId": "candidate-uuid",
  "agentId": "agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
  // jobId is optional - system uses candidate's first job
}

Candidate with Multiple Jobs

When a candidate is associated with multiple jobs, you must specify the jobId to indicate which job the interview is for:

{
  "candidateId": "candidate-uuid",
  "jobId": "job-uuid",  // Required when candidate has multiple jobs
  "agentId": "agent-uuid",
  "scheduleTime": "2024-01-20T14:00:00Z"
}

Multiple Job Assignments: If a candidate has multiple job assignments and you don’t provide jobId, the API will return a 400 Bad Request error with the message “Job ID must be provided when candidate has multiple job assignments”.This applies only to job-requiring focuses. GENERIC and custom (flow-based) agents are job-optional, so they interview a multi-job candidate without a jobId — and a custom agent rejects one outright.

Job Association: The jobId you provide must belong to the same company as your API key. If the candidate is not already assigned to this job, they will be automatically assigned to it when the interview is created.

Job Selection Rules: - jobId and job are XOR (mutually exclusive): - If you provide jobId, you must omit job. - If you provide job, you must omit jobId. - When job is used: - A new job is created for your company. - That job is used as the interview’s jobId. - The candidate is associated with that job automatically before the interview is created.

Company Isolation

All resources (candidate, agent, job) must belong to the same company as your API key. The API automatically validates company ownership and returns 403 Forbidden if resources belong to different companies.

Complete Workflow Examples

Scenario 1: Interview with Job Association

// 1. Create a job (if not exists)
const job = await createJob({
  title: "Senior Software Engineer",
  status: "OPEN",
});

// 2. Create interview with inline candidate linked to job
const interview = await createInterview({
  candidate: {
    jobId: job.id,
    firstName: "Jane",
    lastName: "Doe",
    email: "jane@example.com",
    phoneNumber: "+1234567890",
    gdprExpiryDate: "2026-11-16",
  },
  agentId: "agent-uuid",
  scheduleTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // Tomorrow
});

// 3. Monitor interview status
const status = await getInterview(interview.id);
console.log(`Interview status: ${status.status}`);

Scenario 2: Interview without Job Association (Talent Pool)

// 1. Create interview for candidate in talent pool (no job specified)
const interview = await createInterview({
  candidate: {
    firstName: "John",
    lastName: "Smith",
    email: "john@example.com",
    phoneNumber: "+1234567890",
    gdprExpiryDate: "2026-11-16",
  },
  agentId: "agent-uuid",
  scheduleTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
});

// 2. Later, assign candidate to specific job(s) if needed
const candidateId = interview.candidateId;
await updateCandidate(candidateId, {
  jobIds: ["job-uuid-1", "job-uuid-2"],
});

Scenario 3: Interview for Candidate with Multiple Jobs

// 1. Candidate is associated with multiple jobs
const candidate = await getCandidate("candidate-uuid");
// candidate.jobIds = ["job-1-uuid", "job-2-uuid", "job-3-uuid"]

// 2. Create interview for a specific job (jobId is required)
const interview = await createInterview({
  candidateId: "candidate-uuid",
  jobId: "job-2-uuid", // Must specify which job
  agentId: "agent-uuid",
  scheduleTime: "2024-01-20T14:00:00Z",
});

// 3. Interview is now associated with job-2-uuid
console.log(`Interview created for job: ${interview.jobId}`);

Scenario 4: Existing Candidate with Inline Job

// 1. Candidate already exists in your system
const candidateId = "candidate-uuid";

// 2. Create interview and define job inline
const interview = await createInterview({
  candidateId,
  job: {
    jobTitle: "Senior Backend Engineer",
    jobDescription: "We are looking for a senior engineer...",
    requiredSkills: ["TypeScript", "NestJS", "PostgreSQL"],
    niceToHaveSkills: ["Redis", "AWS"],
    languages: ["EN"],
    experience: "SENIOR",
    contractType: "FULL_TIME",
    location: { workMode: "REMOTE", countryCode: "SK" },
    metadata: { externalJobId: "JOB-12345" },
  },
  agentId: "agent-uuid",
  scheduleTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
});

console.log(`Interview jobId: ${interview.jobId}`);

The inline job is saved as a regular Job entity. You can later fetch and manage it via the Jobs API using the jobId returned in the interview object.

Test Mode

Test mode allows you to create test interviews that immediately complete without consuming billing minutes. This is useful for testing webhook handlers and integration flows.

When to Use Test Mode

Testing Webhook Handlers: Verify that your webhook endpoints correctly handle interview.completed and analysis.completed events
Integration Testing: Test your application’s interview processing logic without waiting for real interviews
Development: Develop and debug features that depend on completed interviews
Demo Purposes: Create sample interviews for demonstrations

How Test Mode Works

When you set isTest: true:

Billing Bypass: All billing checks are skipped - no minutes are consumed
Immediate Completion: The interview is created with COMPLETED status immediately
Mock Analysis Data: Realistic screening analysis data is automatically generated and stored
Webhook Events: Both interview.completed and analysis.completed webhook events are triggered
Default Duration: Test interviews have a default duration of 5 minutes

Example: Creating a Test Interview

const testInterview = await createInterview({
  candidate: {
    firstName: "Jane",
    lastName: "Doe",
    email: "jane@example.com",
    phoneNumber: "+1234567890",
    gdprExpiryDate: "2026-11-16",
  },
  agentId: "agent-uuid",
  isTest: true, // Enable test mode
});

console.log(`Test interview created: ${testInterview.id}`);
console.log(`Status: ${testInterview.status}`); // "COMPLETED"
console.log(`Duration: ${testInterview.durationMinutes} minutes`); // 5

Test Interview Characteristics

Status: Always COMPLETED immediately
Duration: 5 minutes (300 seconds)
Analysis: Includes mock screening analysis with:
- Conversation check results (candidateInterest: true, conversationCompleted: true)
- Candidate analysis scores and recommendations
- Mock transcript segments
Webhooks: Triggers both interview.completed and analysis.completed events
Billing: No minutes consumed, no billing checks performed

Test interviews are marked with isTest: true in their metadata. They appear in interview lists and can be queried like normal interviews, but they do not affect billing or production metrics.

Interviews Resource Guide

Learn about interview management and analysis

Agents Resource Guide

Configure AI interview agents

Candidates Resource Guide

Manage candidate profiles

Billing Guide

Understand interview costs and limits

Webhooks Guide

Learn about webhook events and testing

Authorizations

Authorization

string

header

required

API key for authentication using Bearer scheme

Query Parameters

companyId

string

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

Body

application/json

candidateId

string<uuid>

required

Existing candidate ID (XOR with candidate). Must exist and belong to the same company as the API key. Existence/company relationship is validated server-side.

Example:

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

jobId

string<uuid>

required

Job ID to associate the interview with (XOR with job). Required when the candidate has multiple job assignments and no job is provided, unless the agent's focus is job-optional (GENERIC, CUSTOM). Must belong to the API key's company. If the candidate is not already assigned to this job, they will be automatically assigned. Rejected with 400 for custom agents (agents defined by a conversation flow), which are always jobless.

Example:

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

agentId

string<uuid>

required

Existing agent ID (XOR with agent). Must exist and belong to the same company as the API key. Existence/company relationship is validated server-side.

Example:

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

scheduleTime

string<date-time>

required

Scheduled time in ISO 8601 format (max 30 days in future)

Example:

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

job

object

Job for inline creation (XOR with jobId). When provided, a new job will be created and used for the interview. Cannot be combined with jobId. Rejected with 400 for custom agents (agents defined by a conversation flow), which are always jobless.

Show child attributes

candidate

object

Candidate for inline creation (XOR with candidateId)

Show child attributes

agent

object

Agent for inline creation (XOR with agentId)

Option 1
Option 2

Show child attributes

metadata

object

Custom metadata for the interview (max 10KB, 5 levels deep, 50 keys)

Example:

{
  "externalInterviewId": "INT-789",
  "interviewerNotes": "Focus on technical skills"
}

isTest

boolean

default:false

If true, creates a test interview that immediately completes without consuming billing minutes. Triggers webhook events (interview.completed, analysis.completed) for testing webhook handlers.

Example:

false

Response

OK (legacy; prefer 201)

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,

UNREACHABLE

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.

Show child attributes

analysis

object

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

Show child attributes

analytics

object

What the agent's own analytics configuration produced on this call: extracted fields, match score, outcomes and tags. Present only for a custom agent whose after-call analysis has run.

Show child attributes

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

​Overview

​Use Cases

​Inline Candidate, Agent, and Job Support

​Inline Candidate with Job Association

​Inline Candidate with Inline Job

​Inline Candidate without Job Association

​Inline Custom Agent

​Generic Focus and Jobless Interviews

​Creating a Jobless Interview with GENERIC Focus

​Existing Candidate with Inline Job

​Billing and Limits

​Scheduling Options

​Immediate Interview

​Scheduled Interview

​Job Selection for Existing Candidates

​Candidate with Single Job

​Candidate with Multiple Jobs

​Company Isolation

​Complete Workflow Examples

​Scenario 1: Interview with Job Association

​Scenario 2: Interview without Job Association (Talent Pool)

​Scenario 3: Interview for Candidate with Multiple Jobs

​Scenario 4: Existing Candidate with Inline Job

​Test Mode

​When to Use Test Mode

​How Test Mode Works

​Example: Creating a Test Interview

​Test Interview Characteristics

​Related Resources

Interviews Resource Guide

Agents Resource Guide

Candidates Resource Guide

Billing Guide

Webhooks Guide

Authorizations

Query Parameters

Body

Response

Overview

Use Cases

Inline Candidate, Agent, and Job Support

Inline Candidate with Job Association

Inline Candidate with Inline Job

Inline Candidate without Job Association

Inline Custom Agent

Generic Focus and Jobless Interviews

Creating a Jobless Interview with GENERIC Focus

Existing Candidate with Inline Job

Billing and Limits

Scheduling Options

Immediate Interview

Scheduled Interview

Job Selection for Existing Candidates

Candidate with Single Job

Candidate with Multiple Jobs

Company Isolation

Complete Workflow Examples

Scenario 1: Interview with Job Association

Scenario 2: Interview without Job Association (Talent Pool)

Scenario 3: Interview for Candidate with Multiple Jobs

Scenario 4: Existing Candidate with Inline Job

Test Mode

When to Use Test Mode

How Test Mode Works

Example: Creating a Test Interview

Test Interview Characteristics

Related Resources