The Gong Calls API provides endpoints to retrieve, add, and manage call data including recordings, transcripts, and media files. It supports filtering calls by date range, retrieving detailed call analytics, and uploading call recordings from external telephony systems.
openapi: 3.1.0
info:
title: Gong Calls API
description: >-
The Gong Calls API provides endpoints to retrieve, add, and manage call data
including recordings, transcripts, and media files. It supports filtering
calls by date range, retrieving detailed call analytics, and uploading call
recordings from external telephony systems.
version: 2.0.0
contact:
name: Gong
url: https://www.gong.io
email: [email protected]
license:
name: Proprietary
url: https://www.gong.io/terms-of-service/
termsOfService: https://www.gong.io/terms-of-service/
servers:
- url: https://api.gong.io/v2
description: Gong API v2 Production Server
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Calls
description: Operations for managing and retrieving call data
- name: Recordings
description: Operations for managing call recordings and media
- name: Transcripts
description: Operations for retrieving call transcripts
paths:
/calls:
get:
operationId: listCalls
summary: Gong List calls
description: >-
Retrieves a list of calls that took place during a specified date range.
Results are paginated and can be filtered by workspace.
tags:
- Calls
parameters:
- name: fromDateTime
in: query
required: true
description: >-
The start date and time for the calls filter in ISO-8601 format
(e.g., 2021-01-01T00:00:00Z).
schema:
type: string
format: date-time
- name: toDateTime
in: query
required: true
description: >-
The end date and time for the calls filter in ISO-8601 format
(e.g., 2021-12-31T23:59:59Z).
schema:
type: string
format: date-time
- name: cursor
in: query
required: false
description: >-
A cursor for pagination. Pass the cursor from the previous response
to retrieve the next page of results.
schema:
type: string
- name: workspaceId
in: query
required: false
description: Optional workspace identifier to filter calls by workspace.
schema:
type: string
responses:
'200':
description: Successful response containing a list of calls.
content:
application/json:
schema:
$ref: '#/components/schemas/CallsResponse'
'400':
description: Bad request due to invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: addCall
summary: Gong Add a new call
description: >-
Adds a new call record to Gong. Either provide a downloadMediaUrl in the
request body or use the returned callId in a follow-up request to
/v2/calls/{id}/media to upload the media file.
tags:
- Calls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewCallAddingRequest'
responses:
'201':
description: Call successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/NewCallAddingResponse'
'400':
description: Bad request due to invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/{id}:
get:
operationId: getCall
summary: Gong Retrieve a specific call
description: >-
Retrieves detailed information about a specific call identified by its
unique numeric identifier.
tags:
- Calls
parameters:
- name: id
in: path
required: true
description: >-
Gong's unique numeric identifier for the call (up to 20 digits).
schema:
type: string
responses:
'200':
description: Successful response containing the call details.
content:
application/json:
schema:
$ref: '#/components/schemas/SpecificCallResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Call not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/{id}/media:
put:
operationId: addCallRecording
summary: Gong Add call media recording
description: >-
Adds call media (audio or video recording) to a previously created call.
Gong accepts recordings in WAV, MP3, MP4, MKV, and FLAC formats up to
1.5GB in size.
tags:
- Recordings
parameters:
- name: id
in: path
required: true
description: The callId returned from the Add New Call request.
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
mediaFile:
type: string
format: binary
description: >-
The audio or video file to upload. Supported formats include
WAV, MP3, MP4, MKV, and FLAC. Maximum size is 1.5GB.
required:
- mediaFile
responses:
'200':
description: Media successfully uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/NewCallRecordingResponse'
'400':
description: Bad request due to invalid file format or size.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Call not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/extensive:
post:
operationId: listCallsExtensive
summary: Gong Retrieve detailed call data
description: >-
Retrieves extensive call data including participants, topics, trackers,
comments, scorecards, and other analytics. Supports filtering by date
range, call IDs, or hosting users. Requires the scope
api:calls:read:extensive.
tags:
- Calls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensiveCallsRequest'
responses:
'200':
description: Successful response containing detailed call data.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensiveCallsResponse'
'400':
description: Bad request due to invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/transcript:
post:
operationId: getCallTranscripts
summary: Gong Retrieve call transcripts
description: >-
Retrieves transcript data for calls matching the specified filter
criteria. Transcripts include speaker identification and timing
information.
tags:
- Transcripts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CallTranscriptRequest'
responses:
'200':
description: Successful response containing call transcripts.
content:
application/json:
schema:
$ref: '#/components/schemas/CallTranscriptsResponse'
'400':
description: Bad request due to invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/manual-crm-associations:
get:
operationId: listManualCrmAssociations
summary: Gong List calls manually associated with CRM
description: >-
Retrieves a list of calls that were manually associated with CRM objects
by users. This endpoint is in beta phase. Results can be filtered by
association time.
tags:
- Calls
parameters:
- name: fromDateTime
in: query
required: false
description: >-
Filter by the time the manual association was created, in ISO-8601
format.
schema:
type: string
format: date-time
- name: cursor
in: query
required: false
description: >-
A cursor for pagination. Pass the cursor from the previous response
to retrieve the next page of results.
schema:
type: string
responses:
'200':
description: >-
Successful response containing a list of manually associated calls.
content:
application/json:
schema:
$ref: '#/components/schemas/ManualAssociationResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/calls/users-access:
post:
operationId: retrieveUserCallAccess
summary: Gong Retrieve user call access
description: >-
Retrieves the list of users who have access to specified calls and their
access levels.
tags:
- Calls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCallAccessRequest'
responses:
'200':
description: Successful response containing user call access data.
content:
application/json:
schema:
$ref: '#/components/schemas/UserCallAccessResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
operationId: giveUserCallAccess
summary: Gong Give user call access
description: >-
Grants specified users access to specified calls within the Gong
platform.
tags:
- Calls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCallAccessUpdateRequest'
responses:
'200':
description: Call access successfully granted.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: removeUserCallAccess
summary: Gong Remove user call access
description: >-
Removes specified users' access to specified calls within the Gong
platform.
tags:
- Calls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCallAccessUpdateRequest'
responses:
'200':
description: Call access successfully removed.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
'401':
description: Unauthorized - invalid or missing authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication using your Gong API access key and secret. Format:
base64(access_key:access_secret).
bearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 Bearer token authentication.
schemas:
CallsResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
records:
type: object
properties:
totalRecords:
type: integer
description: Total number of call records matching the filter.
currentPageSize:
type: integer
description: Number of records in the current page.
currentPageNumber:
type: integer
description: The current page number.
cursor:
type: string
description: Cursor value for retrieving the next page of results.
calls:
type: array
items:
$ref: '#/components/schemas/Call'
description: List of call objects.
Call:
type: object
properties:
id:
type: string
description: Unique numeric identifier for the call.
title:
type: string
description: The title or subject of the call.
url:
type: string
format: uri
description: URL to the call in the Gong web application.
scheduled:
type: string
format: date-time
description: Scheduled start time of the call in ISO-8601 format.
started:
type: string
format: date-time
description: Actual start time of the call in ISO-8601 format.
duration:
type: number
description: Duration of the call in seconds.
direction:
type: string
enum:
- Inbound
- Outbound
- Conference
- Unknown
description: The direction of the call.
scope:
type: string
enum:
- Internal
- External
- Unknown
description: Whether the call was internal or external.
media:
type: string
enum:
- Video
- Audio
description: The type of media recorded.
language:
type: string
description: The detected language of the call.
workspaceId:
type: string
description: The workspace identifier the call belongs to.
primaryUserId:
type: string
description: The Gong user ID of the primary user on the call.
parties:
type: array
items:
$ref: '#/components/schemas/CallParty'
description: The participants in the call.
CallParty:
type: object
properties:
id:
type: string
description: Unique identifier for the party.
emailAddress:
type: string
format: email
description: Email address of the party.
name:
type: string
description: Display name of the party.
title:
type: string
description: Job title of the party.
userId:
type: string
description: Gong user ID if the party is a Gong user.
speakerId:
type: string
description: Speaker identifier within the call.
affiliation:
type: string
enum:
- Internal
- External
- Unknown
description: Whether the party is internal or external.
phoneNumber:
type: string
description: Phone number of the party.
methods:
type: array
items:
type: string
description: Communication methods used by the party.
NewCallAddingRequest:
type: object
required:
- actualStart
- clientUniqueId
- direction
- parties
- primaryUser
properties:
actualStart:
type: string
format: date-time
description: The actual start time of the call in ISO-8601 format.
clientUniqueId:
type: string
description: >-
A unique identifier for the call provided by the client to prevent
duplicates.
direction:
type: string
enum:
- Inbound
- Outbound
- Conference
- Unknown
description: The direction of the call.
downloadMediaUrl:
type: string
format: uri
description: >-
Optional URL from which Gong can download the call recording media.
If not provided, use /v2/calls/{id}/media to upload.
duration:
type: number
description: Duration of the call in seconds.
languageCode:
type: string
description: Language code of the call for transcription.
meetingUrl:
type: string
format: uri
description: URL of the meeting (if applicable).
parties:
type: array
items:
$ref: '#/components/schemas/NewCallParty'
description: List of call participants.
primaryUser:
type: string
description: Email address of the primary Gong user on the call.
purpose:
type: string
description: The purpose or subject of the call.
scheduledEnd:
type: string
format: date-time
description: The scheduled end time of the call.
scheduledStart:
type: string
format: date-time
description: The scheduled start time of the call.
title:
type: string
description: The title of the call.
workspaceId:
type: string
description: The workspace to associate the call with.
NewCallParty:
type: object
properties:
emailAddress:
type: string
format: email
description: Email address of the participant.
name:
type: string
description: Display name of the participant.
phoneNumber:
type: string
description: Phone number of the participant.
userId:
type: string
description: Gong user ID of the participant (if applicable).
NewCallAddingResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
callId:
type: string
description: >-
The Gong-assigned unique identifier for the newly created call.
NewCallRecordingResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
callId:
type: string
description: The call ID the media was attached to.
SpecificCallResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
call:
$ref: '#/components/schemas/Call'
ExtensiveCallsRequest:
type: object
properties:
cursor:
type: string
description: Cursor for pagination.
filter:
type: object
properties:
fromDateTime:
type: string
format: date-time
description: Start of the date range filter.
toDateTime:
type: string
format: date-time
description: End of the date range filter.
callIds:
type: array
items:
type: string
description: Specific call IDs to retrieve.
workspaceId:
type: string
description: Filter by workspace.
description: Filter criteria for calls.
contentSelector:
type: object
properties:
context:
type: string
enum:
- None
- Extended
- Full
description: Level of context to include.
exposedFields:
type: object
properties:
collaboration:
type: boolean
description: Include collaboration data.
content:
type: boolean
description: Include content data.
currentSpeakerUserIds:
type: boolean
description: Include speaker user IDs.
media:
type: boolean
description: Include media URLs (requires api:calls:read:media-url scope).
parties:
type: boolean
description: Include party information.
publicComments:
type: boolean
description: Include public comments.
description: Fields to include in the response.
description: Selector for what content to include in the response.
ExtensiveCallsResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
records:
type: object
properties:
totalRecords:
type: integer
description: Total number of matching records.
currentPageSize:
type: integer
description: Number of records in the current page.
cursor:
type: string
description: Cursor for retrieving the next page.
calls:
type: array
items:
$ref: '#/components/schemas/DetailedCall'
description: List of detailed call objects.
DetailedCall:
allOf:
- $ref: '#/components/schemas/Call'
- type: object
properties:
content:
type: object
properties:
topics:
type: array
items:
type: object
properties:
name:
type: string
duration:
type: number
description: Topics discussed during the call.
trackers:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
count:
type: integer
occurrences:
type: array
items:
type: object
properties:
startTime:
type: number
speakerId:
type: string
description: Tracked keywords and phrases.
pointsOfInterest:
type: object
properties:
actionItems:
type: array
items:
type: object
properties:
snippet:
type: string
speakerId:
type: string
description: Key points and action items.
description: Content analysis data.
collaboration:
type: object
properties:
publicComments:
type: array
items:
type: object
properties:
id:
type: string
commenterUserId:
type: string
comment:
type: string
audioStartTime:
type: number
posted:
type: string
format: date-time
description: Public comments on the call.
description: Collaboration data.
interaction:
type: object
properties:
speakers:
type: array
items:
type: object
properties:
id:
type: string
userId:
type: string
talkTime:
type: number
description: Speaker statistics.
interactivity:
type: number
description: Interactivity score.
description: Interaction statistics.
media:
type: object
properties:
audioUrl:
type: string
format: uri
description: URL for the audio recording.
videoUrl:
type: string
format: uri
description: URL for the video recording.
description: Media URLs for the call recording.
CallTranscriptRequest:
type: object
properties:
cursor:
type: string
description: Cursor for pagination.
filter:
type: object
properties:
callIds:
type: array
items:
type: string
description: List of call IDs to retrieve transcripts for.
fromDateTime:
type: string
format: date-time
description: Start of the date range filter.
toDateTime:
type: string
format: date-time
description: End of the date range filter.
workspaceId:
type: string
description: Filter by workspace.
description: Filter criteria for transcript retrieval.
CallTranscriptsResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
records:
type: object
properties:
totalRecords:
type: integer
currentPageSize:
type: integer
cursor:
type: string
callTranscripts:
type: array
items:
$ref: '#/components/schemas/CallTranscript'
description: List of call transcripts.
CallTranscript:
type: object
properties:
callId:
type: string
description: The call ID this transcript belongs to.
transcript:
type: array
items:
type: object
properties:
speakerId:
type: string
description: ID of the speaker.
topic:
type: string
description: Topic of the segment.
sentences:
type: array
items:
type: object
properties:
start:
type: number
description: Start time in seconds.
end:
type: number
description: End time in seconds.
text:
type: string
description: The transcribed text.
description: Transcript segments with speaker and timing data.
ManualAssociationResponse:
type: object
properties:
requestId:
type: string
description: A unique identifier for the request.
records:
type: object
properties:
totalRecords:
type: integer
currentPageSize:
type: integer
cursor:
type: string
calls:
type: array
items:
type: object
properties:
callId:
type: string
description: The call ID.
crmAssociations:
type: array
items:
type: object
properties:
objectType:
type: string
objectId:
type: string
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gong/refs/heads/main/openapi/gong-calls-openapi.yml