curl --request GET \
--url https://api.instaview.sk/conversations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/conversations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/conversations', 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/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/conversations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"contactId": "987e6543-e21b-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",
"runId": "789e0123-e45b-67d8-a901-234567890123",
"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,
"scoringIncompleteReason": "model_unavailable",
"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",
"type": "string",
"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,
"importance": "REQUIRED",
"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,
"trajectory": "improving",
"notes": "<string>"
},
"summary": "Qualified lead; demo booked for Thursday."
},
"isTest": false
}
],
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}List Conversations
Lists conversations within the API key’s company. Every filter is optional: pass contactId to narrow the page to one contact (candidateId is accepted as its legacy alias), and omit it to list all of them.
curl --request GET \
--url https://api.instaview.sk/conversations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/conversations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/conversations', 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/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/conversations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"contactId": "987e6543-e21b-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",
"runId": "789e0123-e45b-67d8-a901-234567890123",
"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,
"scoringIncompleteReason": "model_unavailable",
"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",
"type": "string",
"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,
"importance": "REQUIRED",
"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,
"trajectory": "improving",
"notes": "<string>"
},
"summary": "Qualified lead; demo booked for Thursday."
},
"isTest": false
}
],
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}GET /interviews is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.Overview
This endpoint returns the conversations in your API key’s company — useful for showing someone’s call history, following a conversation’s status, and picking up analysis or analytics once a call has finished.Filters
Every filter is optional; omit them all and you get the whole company’s conversations, newest first.| Query parameter | Filters on |
|---|---|
contactId | One contact. candidateId is accepted as its permanent legacy alias |
agentId | One agent |
jobId | The job the conversation itself is for (deprecated) |
status | One status |
Use Cases
- Call history: every conversation for one contact
- Status tracking: follow progress and completion
- Results retrieval: reach analysis, analytics and transcripts
- Pipeline management: track conversations across your own process
Basic Usage
// List all conversations for a contact
GET /conversations?contactId=contact-uuid
With Pagination
// Get first page with 20 items
GET /conversations?contactId=contact-uuid&page=1&limit=20
// Get second page
GET /conversations?contactId=contact-uuid&page=2&limit=20
Status Filtering
status takes one of SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED, FAILED,
UNREACHABLE or UNDEFINED. The values are upper-case, and anything else is rejected with
400 Bad Request before the listing runs.
// Get only completed conversations
GET /conversations?contactId=contact-uuid&status=COMPLETED
Response Structure
Each row carries the conversation’s own fields, plus analysis when there is any:{
"data": [
{
"id": "conversation-uuid",
"contactId": "contact-uuid",
"candidateId": "contact-uuid",
"agentId": "agent-uuid",
"status": "COMPLETED",
"analysis": {
"id": "analysis-uuid",
"general": {
"overallRating": 85,
"companyFitRating": "HIGH",
"strongPoints": ["Strong technical skills"],
"weakPoints": ["Limited leadership experience"]
},
"specific": null
}
}
],
"total": 5,
"page": 1,
"limit": 20,
"totalPages": 1
}
analytics object instead — the same shape returned by GET /conversations/{id}, so a page needs no follow-up request per row to read its results. Such rows typically have no analysis, since the recruiting jobs do not run for them.
Tracking Progress
async function trackConversations(contactId) {
const response = await fetch(
`https://api.instaview.sk/conversations?contactId=${contactId}`,
{
headers: { Authorization: `Bearer ${apiKey}` },
// Without a deadline a stalled request never settles.
signal: AbortSignal.timeout(10_000),
},
);
if (!response.ok) {
throw new Error(
`Listing conversations failed: ${response.status} ${response.statusText}`,
);
}
const { data, total } = await response.json();
return {
total,
completed: data.filter((c) => c.status === "COMPLETED").length,
inProgress: data.filter((c) => c.status === "IN_PROGRESS").length,
scheduled: data.filter((c) => c.status === "SCHEDULED").length,
};
}
Company Isolation
Every conversation returned belongs to a contact in your API key’s company. Conversations from another company are never listed.Related Resources
Conversations Resource Guide
Get Conversation
Pagination Guide
Contacts Resource Guide
Authorizations
API key for authentication using Bearer scheme
Query Parameters
Page number (1-based)
1 <= x <= 100001
Number of items per page
1 <= x <= 10020
Company ID (required for ATS keys, optional for regular keys)
"123e4567-e89b-12d3-a456-426614174000"
Filter by contact ID. Optional; omit it to list every conversation.
"123e4567-e89b-12d3-a456-426614174000"
Deprecated alias of contactId. Optional. Sending both is allowed only when they hold the same value.
"123e4567-e89b-12d3-a456-426614174000"
Filter by agent ID
"987e6543-e21b-12d3-a456-426614174000"
Filter by conversation status
UNDEFINED, SCHEDULED, CANCELLED, FAILED, COMPLETED, IN_PROGRESS, UNREACHABLE "SCHEDULED"
[Deprecated] Filter by the job the conversation is for.
"456e7890-e12b-34d5-a678-901234567890"