Skip to main content
GET
Get conversation by ID
GET /interviews/{id} is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.
Retrieves a single conversation by ID, including full details, transcript, analysis or analytics, and call attempt information.

Overview

This endpoint returns everything recorded about one conversation: its current status, the transcript, the AI analysis or analytics when there is any, and every associated field. It is the primary way to read a call’s results.

Use Cases

  • Read results: analysis, analytics and transcript once the call has finished
  • Check status: follow a conversation’s progress
  • Access transcripts: the full transcript of what was said
  • Review scoring: the AI-generated assessment and its scores

Response Data

The response includes:
  • Conversation details: status, timestamps, duration, scheduled time
  • Transcript: the full transcript, when available
  • Analysis: AI-generated assessment with scores and recommendations
  • Call attempts: each attempt and its recording
  • Contact & agent: contactId (with candidateId alongside it, always identical) and agentId
  • Run: runId, the run that produced this conversation, or null for one created on its own

Analysis Data

Once a conversation has completed, the response carries its analysis. The structure is a general object holding the overall assessment, plus an optional specific object for data particular to the conversation type:
The specific field carries data particular to the conversation type, when there is any. See the Conversations Resource Guide for what each type produces.
Analysis is only available once the conversation has completed. While one is scheduled or in progress, analysis is null.

Custom Agent Analytics

A conversation run by a custom agent carries a second, separate object: analytics, containing whatever that agent’s analyticsConfig asked for. It is not a variant of analysisanalysis is the recruiting pipeline’s output and is typically absent on a custom call, while analytics is the agent’s own design.
The key on each field, outcome and tag is the one configured on the agent, so you can switch on it directly. Reading it back:
  • value: null on a field means the call did not surface it — distinct from a false or empty value that was surfaced.
  • In scoring.items, an entry with kind: "question" carries the flow question’s id rather than a configured key — a question has none, which is why its scoring is set inline on the question. Entries with kind: "field" or "criterion" carry the configured key.
  • weightPercent is each scored item’s share of the match score, so the shares sum to exactly 100. The weights you configured are relative, not percentages.
  • matchScore is always present, and null when scoring has not run yet.
  • In qa, answered: false means the call never reached the question, not that it was answered with nothing — answer is empty in both cases, so switch on answered.
  • evaluation holds four independent arrays of lines (strengths, concerns, objections, assessment); any one can be empty while the others are populated.
  • Each slice is produced by its own after-call job, and each job only runs when the agent asked for it — so an absent outcomes or sentiment means “not configured, or not run yet”.
The same object is pushed to your analysis.completed webhook, so you do not have to poll for it.

Status Checking

Company Isolation

You can only read conversations belonging to contacts in your own company. Reaching for one from another company returns 403 Forbidden.

Error Scenarios

  • 404 Not Found: the conversation does not exist, or has been deleted
  • 403 Forbidden: the conversation belongs to a different company

Conversations Resource Guide

Learn how conversations are run and analysed

List Conversations

List every conversation for one contact

Create Conversation

Schedule a new call

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

Conversation ID

Example:

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

contactId
string<uuid>
required

Contact ID

Example:

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

candidateId
string<uuid>
required
deprecated

Deprecated alias of contactId, always identical to it. Kept for the life of v1 so existing integrations keep working; new callers should read contactId.

Example:

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

agentId
string<uuid>
required

Agent ID

Example:

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

status
enum<string>
required

Conversation 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 conversation, if any

Example:

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

runId
string<uuid> | null

The run that produced this conversation, or null for one created on its own. A run mints one conversation per contact, so this is how a conversation is traced back to the batch it came from without listing the run.

Example:

"789e0123-e45b-67d8-a901-234567890123"

durationMinutes
number

Conversation duration in minutes

Example:

15

finishedDate
string<date-time>

Finished date

Example:

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

metadata
object

Custom metadata

Example:
callAttempts
object[]

Call attempt logs for this conversation. Present for PHONE conversations, typically empty or undefined for ONLINE ones.

analysis
object

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

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.

isTest
boolean

Whether this is a test conversation. A test conversation is created with isTest=true, completes immediately without consuming billing minutes, and is excluded from billing and usage summaries. Use them to exercise webhook handlers and integration flows.

Example:

false