Conversation intelligence — search recorded calls and meetings, read insights, export. 4 operation(s) from the published Apollo OpenAPI.
openapi: 3.1.0
info:
title: Apollo.io Conversations API
version: '1.0'
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment,
prospect and company search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one
sales intelligence and engagement platform. Use it to enrich people and company data (individually
or in bulk), search Apollo''s database of over 240 million contacts and 30 million companies, and
manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market
workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create
API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth
2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing).
Check your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats)
endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the
[API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
servers:
- url: https://api.apollo.io/api/v1
tags:
- name: Conversations
description: Search, export, and retrieve recorded conversations.
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
paths:
/conversations/search:
post:
summary: Search Conversations
description: '## Endpoint essentials
**API key access:** `api/v1/conversations/search` or `Master API key`
**OAuth scopes:** `conversations_search`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
<a href="https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations">Conversations</a>
are prospect video meetings stored in Apollo.<br><br>Use the Search Conversations endpoint to
find a list of conversations. Several filters are available to help narrow your search, including
by type, account, contact, date range, and more. Each result includes a summary of the conversation.<br><br>This
endpoint doesn''t include transcripts or recording URLs. Use the conversation ID retrieved from
your search to request full details using <a href="https://docs.apollo.io/docs/get-conversations-info">Get
Conversations Info</a>.'
tags:
- Conversations
operationId: search-conversations
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
page:
type: integer
description: Page number for pagination.
num_fetch_result:
type: integer
description: Maximum number of results to return.
conversation_type:
type: string
enum:
- video_conference
- phone_call
description: Filter by dialer calls, or video conference calls.
account_id:
type: string
description: Filter by account ID.
contact_ids:
type: array
description: Filter by one or more contact IDs.
items:
type: string
tag_ids:
type: array
description: Filter by label or tag IDs.
items:
type: string
tracker_ids:
type: array
description: Filter by tracker IDs.
items:
type: string
organization_ids:
type: array
description: Filter by organization IDs.
items:
type: string
date_range:
type: object
description: Filter by date range.
properties:
start:
type: string
description: 'Start date (ISO 8601). Apollo uses Greenwich Mean Time (GMT) for all
date and time values. <br><br> Example: <code>2024-01-01T00:00:00Z</code>'
end:
type: string
description: 'End date (ISO 8601). Apollo uses Greenwich Mean Time (GMT) for all
date and time values. <br><br> Example: <code>2024-03-31T23:59:59Z</code>'
scorecard_template_id:
type: string
description: Filter by scorecard template ID.
scorecard_max_rating:
type: number
description: Maximum scorecard rating to include in the results.
sort_by_field:
type: string
description: Field to sort results by.
enforce_contact_boundary:
type: boolean
description: When <code>true</code>, restricts results to conversations visible to the
specified contacts.
examples:
Basic search:
value:
page: 1
num_fetch_result: 25
Filter by account and type:
value:
page: 1
num_fetch_result: 25
account_id: 64a1b2c3d4e5f6a7b8c9d0e1
conversation_type: video_conference
Filter by contact IDs and tags:
value:
page: 1
num_fetch_result: 25
contact_ids:
- 64a1b2c3d4e5f6a7b8c9d0e2
- 64a1b2c3d4e5f6a7b8c9d0e3
tag_ids:
- 5f9a1b2c3d4e5f6a7b8c9d0e
Filter by date range:
value:
page: 1
num_fetch_result: 25
date_range:
start: '2024-01-01T00:00:00Z'
end: '2024-03-31T23:59:59Z'
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
pagination:
type: object
description: Pagination metadata for the result set.
additionalProperties: true
breadcrumbs:
type: object
description: Breadcrumbs data associated with the results.
additionalProperties: true
num_fetch_result:
type: integer
description: Number of results returned.
playlist_clip_ids:
type: array
nullable: true
description: IDs of playlist clips associated with the results.
items:
type: string
conversations:
type: array
description: List of conversation summaries matching the search criteria.
items:
type: object
properties:
id:
type: string
description: Unique conversation ID.
topic:
type: string
description: Conversation topic or title.
start_time:
type: string
description: Conversation start time (ISO 8601). Apollo uses Greenwich Mean
Time (GMT) for all date and time values.
duration:
type: integer
description: Duration of the conversation in seconds.
state:
type: string
description: Current processing state of the conversation.
host:
type: string
description: Name of the conversation host.
host_id:
type: string
description: User ID of the conversation host.
is_private:
type: boolean
description: Privacy setting of the conversation.
conversation_type:
type: string
enum:
- video_conference
- phone_call
description: Filter by dialer calls, or video conference calls.
can_access_conversation:
type: boolean
description: Whether the authenticated user can access this conversation.
label_id_names:
type: object
description: Label names associated with the conversation.
additionalProperties: true
participant_names:
type: array
description: Names of the conversation participants.
items:
type: string
comment_count:
type: integer
description: Number of comments on the conversation.
account_names:
type: array
description: Names of associated accounts.
items:
type: string
account_ids:
type: array
description: IDs of associated accounts.
items:
type: string
organization:
type: object
description: Organization associated with the result.
properties:
domain:
type: string
nullable: true
description: Organization domain.
logo_url:
type: string
nullable: true
description: Organization logo URL.
participants_info:
type: array
description: Detailed information about conversation participants.
items:
type: object
thumbnail_url:
type: string
description: URL of the conversation thumbnail image.
is_internal:
type: boolean
description: Whether the conversation is internal.
deals:
type: array
description: Deals associated with the conversation.
items:
type: object
properties:
id:
type: string
description: Deal ID.
account_name:
type: string
description: Name of the associated account.
name:
type: string
description: Deal name.
opportunity_stage_id:
type: string
description: ID of the opportunity stage.
examples:
Basic search results:
value:
pagination:
page: 1
per_page: 25
total_entries: 2
total_pages: 1
breadcrumbs: {}
num_fetch_result: 25
playlist_clip_ids: []
conversations:
- id: 64a1b2c3d4e5f6a7b8c9d0e1
topic: Q3 Sales Review
start_time: '2024-03-15T14:00:00Z'
duration: 3600
state: insights_generated
host: Alice Smith
host_id: 60a5c0b8e4b0c7001c4f1234
is_private: false
conversation_type: phone_call
can_access_conversation: true
label_id_names:
5f9a1b2c3d4e5f6a7b8c9d0e: Follow-up
participant_names:
- Alice Smith
- Bob Jones
comment_count: 3
account_names:
- Acme Corp
account_ids:
- 64a1b2c3d4e5f6a7b8c9d0f2
participants_info: []
thumbnail_url: https://storage.apollo.io/thumbnails/64a1b2c3d4e5f6a7b8c9d0e1.jpg
is_internal: false
deals:
- id: 64a1b2c3d4e5f6a7b8c9d0e3
account_name: Acme Corp
name: Acme Corp - Enterprise Deal
opportunity_stage_id: 5f9a1b2c3d4e5f6a7b8c9d1f
- id: 64a1b2c3d4e5f6a7b8c9d0e2
topic: Product Demo
start_time: '2024-03-16T10:00:00Z'
duration: 1800
state: insights_generated
host: Bob Jones
host_id: 60a5c0b8e4b0c7001c4f5678
is_private: false
conversation_type: phone_call
can_access_conversation: true
label_id_names: {}
participant_names:
- Bob Jones
- Carol Lee
comment_count: 0
account_names:
- Globex Corp
account_ids:
- 64a1b2c3d4e5f6a7b8c9d0f3
participants_info: []
thumbnail_url: https://storage.apollo.io/thumbnails/64a1b2c3d4e5f6a7b8c9d0e2.jpg
is_internal: false
deals: []
'403':
description: '403'
content:
application/json:
examples:
Access denied:
value:
error: Access denied.
schema:
type: object
properties:
error:
type: string
deprecated: false
/conversations/{id}:
get:
summary: Get Conversations Info
description: '## Endpoint essentials
**API key access:** `api/v1/conversations/show` or `Master API key`
**OAuth scopes:** `conversations_show`
**Credit usage:** `0–1 credit per conversation`
This endpoint consumes 1 Apollo credit per conversation if the conversation has AI insights. Conversations
without AI insights consume 0 credits. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing).
<a href="https://knowledge.apollo.io/hc/en-us/articles/45998035787533-Use-Conversations">Conversations</a>
are prospect video meetings stored in Apollo.<br><br>Use the Get Conversation Info endpoint to
retrieve the full details of a single conversation by its ID.<br><br>To get a conversation''s
ID, refer to <a href="https://docs.apollo.io/docs/search-conversations">Search Conversations</a>.'
tags:
- Conversations
operationId: get-conversations-info
parameters:
- name: id
in: path
required: true
description: The conversation ID. Supports an optional share ID in the format <code>id_shareid</code>
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique conversation ID.
topic:
type: string
description: Conversation topic or title.
start_time:
type: string
description: Conversation start time (ISO 8601). Apollo uses Greenwich Mean Time (GMT)
for all date and time values.
duration:
type: integer
description: Duration of the conversation in seconds.
state:
type: string
description: Current processing state of the conversation.
host:
type: string
description: Name of the conversation host.
host_id:
type: string
description: User ID of the conversation host.
is_private:
type: boolean
description: Privacy setting of the conversation.
pushed_to_crm:
type: boolean
description: Whether the conversation has been pushed to a CRM.
account_ids:
type: array
description: IDs of accounts associated with the conversation.
items:
type: string
label_id_names:
type: array
description: Map of label IDs to label names associated with the conversation.
items:
type: string
is_shared_conversation:
type: boolean
description: Whether the conversation has been shared.
opportunity_ids:
type: array
description: IDs of opportunities associated with the conversation.
items:
type: string
comment_count:
type: integer
description: Number of comments on the conversation.
failure_code:
type: string
nullable: true
description: Error code if the conversation processing failed. Returns <code>null</code>
if no failure occurred.
bot_call_ended_reason:
type: string
nullable: true
description: Reason the bot call ended. Returns <code>null</code> if not applicable.
conversation_type:
type: string
enum:
- video_conference
- phone_call
description: Type of conversation.
is_clip:
type: boolean
description: Whether the conversation is a clip.
video_recording:
type: object
description: Video recording details for the conversation.
properties:
type_cd:
type: string
description: Video recording type code.
url:
type: string
description: URL of the video recording.
state_cd:
type: string
description: Processing state code of the video recording.
audio_recording:
type: object
description: Audio recording details for the conversation.
properties:
url:
type: string
description: URL of the audio recording.
transcript:
type: array
description: Transcript of the conversation.
items:
type: object
participants:
type: object
description: Participants in the conversation, grouped by internal and external.
properties:
internal:
type: array
description: Internal participants.
items:
type: object
external:
type: object
description: External participants.
additionalProperties: true
opportunities:
type: array
description: Opportunities associated with the conversation.
items:
type: object
properties:
id:
type: string
description: Opportunity ID.
name:
type: string
description: Opportunity name.
amount:
type: number
nullable: true
description: Opportunity amount.
closed_date:
type: string
nullable: true
description: Close date (ISO 8601).
created_at:
type: string
description: Creation timestamp (ISO 8601).
last_sync:
type: string
nullable: true
description: Last CRM sync timestamp (ISO 8601).
account:
type: object
nullable: true
description: Account this opportunity belongs to.
properties:
id:
type: string
description: Account ID.
name:
type: string
description: Account name.
crm_record_url:
type: string
nullable: true
description: Deep link to the opportunity in the connected CRM.
opportunity_crm_id:
type: string
nullable: true
description: Opportunity ID in the connected CRM.
opportunity_stage_id:
type: string
nullable: true
description: ID of the opportunity stage.
stage_name:
type: string
nullable: true
description: Display name of the opportunity stage.
owner_id:
type: string
nullable: true
description: User ID of the opportunity owner.
initial_opportunity_stage_id:
type: string
nullable: true
description: Original opportunity stage ID when the conversation was first associated.
playlist_clip_ids:
type: array
nullable: true
description: IDs of the playlist clips associated with the conversation.
items:
type: string
examples:
Conversation with insights:
value:
id: 64a1b2c3d4e5f6a7b8c9d0e1
topic: 30 Minute Meeting - Sarah Chen and Marcus Webb
start_time: '2025-03-15T14:00:00.000+00:00'
duration: 289
state: insights_generated
host: Sarah Chen
host_id: 60a5c0b8e4b0c7001c4f1234
is_private: false
pushed_to_crm: false
account_ids:
- 64a1b2c3d4e5f6a7b8c9d0f2
label_id_names: []
is_shared_conversation: false
opportunity_ids:
- 64a1b2c3d4e5f6a7b8c9d0e3
comment_count: 0
failure_code: null
bot_call_ended_reason: timeout_exceeded_everyone_left
conversation_type: video_conference
is_clip: false
video_recording:
type_cd: video
url: https://storage.googleapis.com/apollo-recordings/64a1b2c3d4e5f6a7b8c9d0e1/64a1b2c3d4e5f6a7b8c9d0e1_video.mp4
state_cd: created
transcript:
- id: 64a1b2c3d4e5f6a7b8c9d0f3
start_time: 20880
end_time: 21760
spoken_sentence: Hello? Hello? Hello.
words:
- - Hello?
- 20880
- 21120
- - Hello?
- 21120
- 21400
- - Hello.
- 21400
- 21760
participant_id: 64a1b2c3d4e5f6a7b8c9d0f4
participant_name: Sarah Chen
- id: 64a1b2c3d4e5f6a7b8c9d0f5
start_time: 41050
end_time: 42650
spoken_sentence: Yeah, that works. Let's do it.
words:
- - Yeah,
- 41050
- 41450
- - that
- 41450
- 41649
- - works.
- 41649
- 42010
- - Let's
- 42010
- 42250
- - do
- 42250
- 42370
- - it.
- 42370
- 42650
participant_id: 64a1b2c3d4e5f6a7b8c9d0f6
participant_name: Marcus Webb
participants:
internal: []
external:
others:
- id: 64a1b2c3d4e5f6a7b8c9d0f4
name: Sarah Chen
email: sarah.chen@example.com
account_id: null
organization_id: null
is_organization: true
account_name: null
contact_id: 64a1b2c3d4e5f6a7b8c9d0f8
title: null
account_stage: null
account_arr: null
account_arr_printed: null
- id: 64a1b2c3d4e5f6a7b8c9d0f6
name: Marcus Webb
email: null
account_id: null
organization_id: null
is_organization: true
account_name: null
contact_id: null
title: null
account_stage: null
account_arr: null
account_arr_printed: null
opportunities:
- id: 64a1b2c3d4e5f6a7b8c9d0e3
name: Acme Corp - Enterprise Deal
amount: 6000
closed_date: '2025-06-30T00:00:00.000+00:00'
created_at: '2025-03-01T10:00:00.000Z'
last_sync: null
account:
id: 64a1b2c3d4e5f6a7b8c9d0f2
name: Acme Corp
crm_record_url: null
opportunity_crm_id: null
opportunity_stage_id: 64a1b2c3d4e5f6a7b8c9d0f7
stage_name: Lead
owner_id: 60a5c0b8e4b0c7001c4f1234
initial_opportunity_stage_id: null
playlist_clip_ids: null
Conversation without insights:
value:
id: 64a7ff0cc4dfae00013df1a5
topic: 15 minute meeting - Alice Smith
start_time: '2026-02-26T04:45:00.000+00:00'
duration: 0
state: failed
host: Bob Jones
is_private: null
host_id: 64b8ee1dd5bf9a00014c2b3e
pushed_to_crm: false
account_ids: []
label_id_names: []
is_shared_conversation: false
opportunity_ids: []
comment_count: 0
failure_code: no_video_url
bot_call_ended_reason: timeout_exceeded_waiting_room
conversation_type: video_conference
is_clip: false
recording_source: recall
video_recording:
type_cd: video
url: null
state_cd: created
transcript: []
participants:
internal: []
external: {}
timelines:
participant_timelines: []
unknown_participants_timeline: []
key_topics:
tracker_insights:
trackers_available: true
trackers: null
question_insights: []
call_summary:
outcome: null
pricing_discussion: null
next_steps: []
pain_points: []
objections: []
editable_call_summary:
outcome: nu
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-conversations-api-openapi.yml