> ## Documentation Index > Fetch the complete documentation index at: https://help.gong.io/llms.txt > Use this file to discover all available pages before exploring further. # Add new call > When using this endpoint, either provide a downloadMediaUrl or use the returned callId in a follow-up request to /v2/calls/{id}/media to upload the media file. Required authorizaton scope: 'api:calls:create'. ## OpenAPI ````json POST /v2/calls { "openapi": "3.0.1", "info": { "title": "Gong API", "version": "V2" }, "servers": [ { "url": "http://127.0.0.1:8090", "description": "Generated server url" } ], "tags": [ { "name": "Calls", "description": "

Gong’s “Calls” API endpoints allow you to:

\n\n

The requested calls may contain the following call details:

\n\n" }, { "name": "Users", "description": "

Gong’s “Users” API endpoints allow you to:

\n\n

The requested users may contain the following details:

\n\n" }, { "name": "Stats", "description": "

Gong’s “Stats” API endpoints allow you to:

\n\n

The requested user activity may contain the following details:

\n\n" }, { "name": "Settings", "description": "

Gong’s “Settings” API endpoints allow you to:

\n\n" }, { "name": "Data Privacy", "description": "

Gong’s “Data Privacy” API endpoints allow you to:

\n\n" }, { "name": "Library", "description": "

Gong’s “Library” API endpoints allow you to:

\n\n" }, { "name": "CRM", "description": "

If you are using the deprecated endpoints, download the PDF file.

What does the CRM API do?

This API enables integration with CRMs that are not natively integrated with Gong, so that Gong can provide you with its full capabilities based on your CRM data. This includes:

By uploading your CRM data to Gong, your Gong users will be able to see their CRM deals in the Gong Deals page, view deal boards to follow up on deal progress, get warnings for deals that are at risk, and see whether their team will reach its quota. The CRM data is also displayed in conversations and calls, so that your Gong users can see account and contact data such as the name and job title of the contact in the call. Account data is displayed in the Accounts page, together with the history of all communication and contact with the company.

Note: Gong provides native integrations with Salesforce, HubSpot and Microsoft Dynamics 365.

API Protocol

The API protocol is based on REST guidelines. Check here what's your base URL for all API calls.\n

The payload is either a JSON object or, for API calls that upload lists of objects, line delimited JSON (see: JSON streaming). JSON objects should be UTF-8 encoded.

Dates and timestamps in JSON objects should be in ISO-8601 format without milliseconds (e.g. '2018-02-18T02:30:00-07:00' or '2018-02-18T08:00:00Z', where Z stands for UTC).

What data can I upload?

To see your CRM data in Gong, upload the following entities:

Uploading CRM data to Gong

This diagram shows how to set up your system in order to upload CRM data to Gong. This is relevant for each scenario of uploading data, initial, incremental and uploading historical data.

\"\"

Registering your Integration

Register your integration to get an integrationId used to identify your company's integration with Gong. This is a one time action that does not need to be repeated unless you delete your integration.

Use PUT v2/crm/integrations to register your integration. The integration Id is returned in the response. Include the integration Id each time you upload your CRM data.

Uploading additional data for CRM entities

Each CRM entity has a set of standard fields. In addition, you may want to upload additional fields.

Use the POST /v2/crm/entity-schema to adjust the schema according to your needs. Once you have uploaded your schema to Gong, you can upload your entities with the additional fields.

Uploading your CRM data to Gong

This section explains how you can use the CRM API to upload your data to Gong:

First-time upload

Create a database dump of the data you want to upload to Gong based on your CRM schema and data. When uploading your data for the first time you should include all of the CRM records that should appear in Gong.

Incremental upload

Send regular incremental data updates to Gong. You can update your data as often as you like, we recommend updating between every 1-5 minutes.
You should only send new records or records that have changed since the previous upload of data. New records are added to Gong and existing records are updated or deleted, whichever is relevant. Entities are identified by the objectId. Ensure that this ID remains the same each time it is updated.

When updating data, the modificationDate parameter is mandatory. This enables us to maintain accurate historical data. If your CRM does not store the modification date, send the date the API call is made.

Uploading data change history

Gong incorporates historical change data in different areas of Gong in order to provide a more accurate picture of the status of different entities at that time. For example, showing the correct stage of a deal at the time a call was made.

If your CRM stores record history, you are encouraged to load historical change data as part of the integration. You can do this at any time, but we recommend doing this after the initial upload as follows:

  1. Generate the JSON files with the relevant data. Ensure that the modifiedDate is set to the date the entity was updated.
  2. Upload the entities with their historical data using the POST /v2/crm/entities?objectType=ACCOUNT|CONTACT|DEAL|LEAD endpoint.

Gong Data Model

This diagram shows the connection between the different objects in the CRM API:

\"\"

The following relationship between entities must exist:

What if my CRM doesn't match the Gong data model?

It is possible that your CRM entity model won't match the Gong CRM entity model. Your CRM may store your data in different entities, or you may not have an entity that represents one of the Gong CRM entities.

In order to upload your CRM data and associate it with calls and conversations, you need to identify the objects in your CRM which match the Gong CRM entities.

The account is a mandatory entity which must be uploaded in order to integrate Gong with your CRM. To upload account data, identify your CRM entities that contain data about your customers or companies that you do business with. These customers are not actual people within the org, rather they represent the org itself.

To upload contact details, identify your CRM entities that hold data about employees in the company that your reps are in touch with. A contact represents a person where communication has advanced beyond the prospect stage. Your reps will have multiple conversations and interactions with the contact.

The deal represents the selling process to the customer (account).

The lead is a prospect or potential contact, who is not yet associated with an account. If your CRM has an entity which represents people who you contact in the very early stages, and who is later converted to another entity which represents the people you are doing business with (the contact), upload this data as a lead entity.

When will my CRM data be displayed in Gong?

In addition to the time it takes for data to upload to Gong, the data is first uploaded as raw data and is not automatically available in Gong.





" }, { "name": "Auditing", "description": "

Gong’s “Auditing” API endpoints allow you to request the following log types from Gong:

\n\n" }, { "name": "Meetings (in Beta Phase)", "description": "

Gong’s “Consent Meeting” API endpoints allow you to:

\n\n

The requested calls may contain the following meeting details:

\n\n" }, { "name": "Permissions", "description": "

Gong’s \"Permission\" API endpoints allow you to:

\n\n" }, { "name": "Engage Flows", "description": "

Gong’s “Flows” API endpoints allow you to:

\n\n" }, { "name": "Digital Interactions", "description": "

Digital interactions (DIs) are events people make when interacting with (mostly) digital content. It can be described as an action someone did on an object. Anything from viewing a document or a video, to registering/completing a course or someone visiting your website.

The below proposed Digital Interactions API allows mainly tech-partners (and also customers) to capture and track user interactions with various types of digital content. It provides a structured schema for recording a person’s identity, action, content details, and additional contextual information. The API enables seamless integration between tech-partner systems and the Gong platform, providing valuable insights into buyer-seller interactions that sometimes are hidden from a seller’s line-of-sight.

For simplicity & clarity, the API scheme is designed according to a real-world scenario, including the following terminology:For simplicity & clarity, the API scheme is designed according to a real-world scenario, including the following terminology:

" }, { "name": "Integration Settings", "description": "

Configure your integration settings for displaying your company data in iFrames. For example, use this API to configure dynamic links as the iFrame source. This endpoint includes validation mechanisms to ensure the integration is secure.

Mandatory fields are marked with a *.

" }, { "name": "Engagement (Legacy – See “Digital Interactions”)", "description": "

Limited release - contact integration.requests@gong.io for more information.\n

\n\n

Gong’s \"Engagement\" API endpoints allow you to push engagement events into Gong and display them as events in Gong’s activity timeline.

\n

There are currently 3 types of events:

\n\n" } ], "paths": { "/v2/calls": { "post": { "operationId": "addCall", "summary": "Add new call", "description": "When using this endpoint, either provide a downloadMediaUrl or use the returned callId in a follow-up request to /v2/calls/{id}/media to upload the media file.\n\nRequired authorizaton scope: 'api:calls:create'.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewCallAddingRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewCallAddingResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict, e.g. recording is not enabled for the primary user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "API request limit exceeded", "headers": { "Retry-After": { "description": "Number of seconds to wait before making a new request.", "style": "simple", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Failed to complete the operation due to an unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Calls" ] } } }, "components": { "schemas": { "NewCallAddingRequest": { "description": "New call metadata", "type": "object", "properties": { "clientUniqueId": { "description": "A call's unique identifier in the PBX or the recording system. Gong uses this identifier to prevent repeated attempts to upload the same recording.", "type": "string", "example": "123abc", "maxLength": 2048, "minLength": 0 }, "title": { "description": "The title of the call. This title is used for indexing and search.", "type": "string", "example": "Example call" }, "purpose": { "description": "The purpose of the call.", "type": "string", "example": "Demo Call", "maxLength": 255, "minLength": 0 }, "scheduledStart": { "description": "The date and time the call was scheduled to begin in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00)", "type": "string", "example": "2018-02-17T10:30:00+00:00" }, "scheduledEnd": { "description": "The date and time the call was scheduled to end in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00)", "type": "string", "example": "2018-02-19T10:30:00+00:00" }, "actualStart": { "description": "The actual date and time the call started in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00)", "type": "string", "example": "2018-02-17T10:30:00+00:00" }, "duration": { "description": "The call duration in seconds.", "type": "number", "format": "float", "example": 125.8 }, "parties": { "description": "A list of the call's participants. A party must be provided for the primaryUser.", "type": "array", "items": { "$ref": "#/components/schemas/CallParticipant" }, "maxItems": 2147483647, "minItems": 1 }, "direction": { "description": "Whether the call is inbound (someone called the company), outbound (a rep dialed someone outside the company), or a conference call.", "type": "string", "enum": [ "Inbound", "Outbound", "Conference", "Unknown" ] }, "disposition": { "description": "The disposition of the call. The disposition is free text of up to 255 characters.", "type": "string", "example": "No Answer", "maxLength": 255, "minLength": 0 }, "context": { "description": "A list of references to external systems such as CRM, Telephony System, Case Management, etc.", "type": "array", "items": { "$ref": "#/components/schemas/CallUploadContext" } }, "customData": { "description": "Optional metadata associated with the call (represented as text). Gong stores this metadata and it can be used for troubleshooting.", "type": "string", "example": "Optional data" }, "speakersTimeline": { "$ref": "#/components/schemas/SpeakersTimeline" }, "meetingUrl": { "description": "The URL of the conference call by which users join the meeting", "type": "string", "example": "https://www.conference.com/john.smith" }, "callProviderCode": { "description": "The code identifies the provider conferencing or telephony system. For example: zoom, clearslide, gotomeeting, ringcentral, outreach, insidesales, etc. These values are predefined by Gong, please contact help@gong.io to find the proper value for your system.", "type": "string", "example": "clearslide" }, "downloadMediaUrl": { "description": "The URL from which Gong can download the media file.\nThe URL must be unique, the audio or video file must be a maximum of 1.5GB.\nThe content-type must either start with 'audio' or 'video,' or should be 'application/octet-stream' or 'binary/octet-stream' followed by a subtype that specifies a supported file type (WAV, MP3, MP4, MKV and FLAC).\nIf you provide this URL, you should not perform the 'Add call media' step.", "type": "string", "example": "https://upload-server.com/sample-call.mp3" }, "workspaceId": { "description": "Optional workspace identifier. If specified, the call will be placed into this workspace, otherwise, the default algorithm for workspace placement will be applied.", "type": "string", "example": "623457276584334" }, "languageCode": { "description": "The language code the call should be transcribed to.\nThis field is optional as Gong automatically detects the language spoken in the call and transcribes it accordingly. Set this field only if you are sure of the language the call is in.\nValid values are: af-ZA, am-ET, ar-AE, ar-BH, ar-DZ, ar-EG, ar-IL, ar-IQ, ar-JO, ar-KW, ar-LB, ar-MA, ar-MR, ar-OM, ar-PS, ar-QA, ar-SA, ar-TN, ar-YE, az-AZ, bg-BG, bn-BD, bn-IN, bs-BA, ca-ES, cs-CZ, da-DK, de-AT, de-CH, de-DE, el-GR, en-AB, en-AU, en-CA, en-GB, en-IE, en-IN, en-NZ, en-PH, en-SG, en-US, en-WL, en-ZA, es-AR, es-BO, es-CL, es-CO, es-CR, es-DO, es-EC, es-ES, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, et-EE, eu-ES, fa-IR, fi-FI, fil-PH, fr-BE, fr-CA, fr-CH, fr-FR, gl-ES, gu-IN, he-IL, hi-IN, hr-HR, hu-HU, hy-AM, id-ID, is-IS, it-CH, it-IT, ja-JP, jv-ID, ka-GE, kk-KZ, km-KH, kn-IN, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ml-IN, mn-MN, mr-IN, ms-MY, my-MM, ne-NP, nl-BE, nl-NL, no-NO, pa-Guru-IN, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, si-LK, sk-SK, sl-SI, sq-AL, sr-RS, su-ID, sv-SE, sw-KE, sw-TZ, ta-IN, ta-LK, ta-MY, ta-SG, te-IN, th-TH, tr-TR, uk-UA, ur-IN, ur-PK, uz-UZ, vi-VN, yue-Hant-HK, zh-CN, zh-TW, zu-ZA", "type": "string" }, "flowContext": { "$ref": "#/components/schemas/FlowContext" }, "primaryUser": { "description": "The Gong internal user ID of the team member who hosted the call.", "type": "string", "example": "234599484848423" } }, "required": [ "actualStart", "clientUniqueId", "direction", "parties", "primaryUser" ] }, "NewCallAddingResponse": { "type": "object", "properties": { "requestId": { "description": "A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.", "type": "string", "example": "4al018gzaztcr8nbukw" }, "callId": { "description": "New call ID", "type": "string", "example": "7782342274025937895" } } }, "ErrorResponse": { "type": "object", "properties": { "requestId": { "description": "A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.", "type": "string", "example": "4al018gzaztcr8nbukw" }, "errors": { "description": "Error messages.", "type": "array", "items": { "type": "string" }, "example": [ "An error has occurred" ] } } }, "CallParticipant": { "description": "A list of the call's participants. A party must be provided for the primaryUser.", "type": "object", "properties": { "phoneNumber": { "description": "The phone number of the party, if available.", "type": "string", "example": "+1 123-567-8989" }, "emailAddress": { "description": "The email address of the party, if available.", "type": "string", "example": "test@test.com" }, "name": { "description": "The name of the party, if available.", "type": "string", "example": "Test User" }, "partyId": { "description": "An identifier that is only required when speakersTimeline is provided.\n The partyId is used to recognize the speakers within the provided speakersTimeline.", "type": "string", "example": "1" }, "mediaChannelId": { "description": "The audio channel corresponding to the company team member (rep) used when the uploaded media file is multi-channel (stereo). The channel id is either 0 or 1 (representing left or right respectively)", "type": "integer", "format": "int32", "example": 0, "maximum": 1, "minimum": 0 }, "context": { "description": "A list of links to external systems such as CRM, Telephony System, Case Management, etc.", "type": "array", "items": { "$ref": "#/components/schemas/PartyUploadContext" } }, "userId": { "description": "The user ID of the participant within the Gong system, if the participant is a user.", "type": "string", "example": "234599484848423" } } }, "CallUploadContext": { "description": "Links to external systems such as CRM, Telephony System, Case Management etc. Currently only Salesforce and Generic are supported.", "type": "object", "properties": { "system": { "description": "External system name. Currently only Salesforce and Generic are supported.", "type": "string", "example": "Salesforce", "enum": [ "Salesforce", "HubSpot", "MicrosoftDynamic", "Generic" ] }, "objects": { "description": "List of objects within the external system. Note: Multiple opportunities/deals belonging to the same account are not supported.", "type": "array", "items": { "$ref": "#/components/schemas/ExternalCrmCallObject" } } }, "required": [ "system" ] }, "SpeakersTimeline": { "description": "The audio recording speech segments (who spoke when). Note that speakersTimeline and mediaChannelId are mutually exclusive, when providing speakersTimeline - mediaChannelId will not be used.", "type": "object", "properties": { "precise": { "description": "Indicates whether the provided speech segments match the media precisely or need further refinement based on the media. \"Precisely\" here means that segments do not deviate from the actual speech in the media by more than 100ms.", "type": "boolean", "example": true }, "speechSegments": { "description": "The audio recording speech segments (who spoke when). ", "type": "array", "items": { "$ref": "#/components/schemas/SpeechSegment" } } } }, "FlowContext": { "description": "The Id for the task the call should be associated with", "type": "object", "properties": { "taskId": { "description": "A task identifier", "type": "string", "example": "714366367493425" } } }, "PartyUploadContext": { "description": "Links to external systems such as CRM, Telephony System, Case Management etc. Currently only Salesforce and Generic are supported.", "type": "object", "properties": { "system": { "description": "External system name. Currently only Salesforce and Generic are supported.", "type": "string", "example": "Salesforce", "enum": [ "Salesforce", "HubSpot", "MicrosoftDynamic", "Generic" ] }, "objects": { "description": "List of objects within the external system", "type": "array", "items": { "$ref": "#/components/schemas/ExternalCrmPartyObject" } } }, "required": [ "system" ] }, "ExternalCrmCallObject": { "description": "External object associated with the call", "type": "object", "properties": { "objectType": { "description": "Object Type. e.g. Account.", "type": "string", "example": "Account", "enum": [ "Opportunity", "Account", "Lead", "Contact", "User", "Opportunity,Account" ] }, "objectId": { "description": "Object ID. For Salesforce both case-sensitive and case-insensitive formats are supported.", "type": "string", "example": "0013601230sV7grAAC" }, "fields": { "description": "Object fields. Intended for future use only.", "type": "array", "items": { "$ref": "#/components/schemas/ContextField" } } }, "required": [ "objectId", "objectType" ] }, "SpeechSegment": { "description": "The audio recording speech segments (who spoke when). ", "type": "object", "properties": { "fromTime": { "description": "The start time of the segment in milliseconds from the beginning of the call.", "type": "integer", "format": "int32", "example": 5100, "minimum": 0 }, "toTime": { "description": "The end time of the segment in milliseconds from the beginning of the call.", "type": "integer", "format": "int32", "example": 24000, "minimum": 0 }, "partyIds": { "description": "The speaking parties in the segment, each must have a correlating partyId within 'parties'. It is allowed to provide overlapping segments, i.e. you can either specify multiple speakers in a segment or send several overlapping segments each marked with one speaker.", "type": "array", "items": { "type": "string", "example": "[\"1\"]" }, "example": [ "1" ] } }, "required": [ "fromTime", "partyIds", "toTime" ] }, "ExternalCrmPartyObject": { "description": "External object associated with the party", "type": "object", "properties": { "objectType": { "description": "Object Type. Valid only for non-company parties. e.g. Lead.", "type": "string", "example": "Contact", "enum": [ "Lead", "Contact", "Account", "Opportunity", "User", "Lead,Contact" ] }, "objectId": { "description": "Object ID. For Salesforce both case-sensitive and case-insensitive formats are supported.", "type": "string", "example": "0013601230sV7grAAC" }, "fields": { "description": "Object fields. Intended for future use only.", "type": "array", "items": { "$ref": "#/components/schemas/CrmPartyContextField" } } }, "required": [ "objectId", "objectType" ] }, "ContextField": { "description": "External object data", "type": "object", "properties": { "name": { "description": "Field name. For Account supported fields are: Name, Website, Industry and all the custom fields. For Opportunity supported fields are Name, LeadSource, Type, StageName, Probability, Amount, CloseDate and all the custom fields.", "type": "string", "example": "name" }, "value": { "description": "Field value", "type": "object", "example": "Gong Inc." } } }, "CrmPartyContextField": { "description": "External object data", "type": "object", "properties": { "name": { "description": "Field name", "type": "string", "example": "name" }, "value": { "description": "Object value", "type": "object", "example": "Gong Inc." } } } } } } ````