Skip to main content
GET
List conversations
GET /interviews is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.
Lists conversations with pagination and filtering.

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.

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

With Pagination

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.

Response Structure

Each row carries the conversation’s own fields, plus analysis when there is any:
Both id spellings are always present and always identical, so you can move field by field at your own pace. Rows produced by a custom agent carry an 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

Company Isolation

Every conversation returned belongs to a contact in your API key’s company. Conversations from another company are never listed.

Conversations Resource Guide

Learn how conversations are run and analysed

Get Conversation

Retrieve a single conversation by ID

Pagination Guide

Understand pagination best practices

Contacts Resource Guide

Manage the people you call

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

page
integer
default:1

Page number (1-based)

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

1

limit
integer
default:20

Number of items per page

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

20

companyId
string<uuid>

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

Example:

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

contactId
string<uuid>

Filter by contact ID. Optional; omit it to list every conversation.

Example:

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

candidateId
string<uuid>

Deprecated alias of contactId. Optional. Sending both is allowed only when they hold the same value.

Example:

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

agentId
string<uuid>

Filter by agent ID

Example:

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

status
enum<string>

Filter by conversation status

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

"SCHEDULED"

jobId
string

[Deprecated] Filter by the job the conversation is for.

Example:

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

Response

200 - application/json
data
object[]
required

Array of conversations

total
number
required

Total number of items

Example:

150

page
number
required

Current page number

Example:

1

limit
number
required

Number of items per page

Example:

20

totalPages
number
required

Total number of pages

Example:

8