--- title: "Add new call" slug: "add-new-call-v2calls-2" updated: 2025-11-17T08:10:53Z published: 2025-11-17T08:12:09Z canonical: "help.gong.io/add-new-call-v2calls-2" --- > ## 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 Post/v2/calls When using this endpoint, either provide a downloadMediaUrl or use the returned callId in a follow-up request to /v2/calls//media to upload the media file. Required authorizaton scope: 'api:calls:create'. Body parametersExpand Allobject New call metadata clientUniqueIdstring Required 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. Min length0Max length2048Example123abc titlestring The title of the call. This title is used for indexing and search. ExampleExample call purposestring The purpose of the call. Min length0Max length255ExampleDemo Call scheduledStartstring The date and time the call was scheduled to begin in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00) Example2018-02-17T02:30:00-08:00 scheduledEndstring The date and time the call was scheduled to end in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00) Example2018-02-19T02:30:00-08:00 actualStartstring Required The actual date and time the call started in ISO-8601 format (Use UTC (Z) or a timezone offset (-07:00) Example2018-02-17T02:30:00-08:00 durationnumber (float) The call duration in seconds. Example125.8 parties Array of object (CallParticipant) Required A list of the call's participants. A party must be provided for the primaryUser. Min items1Max items2147483647object A list of the call's participants. A party must be provided for the primaryUser. phoneNumberstring The phone number of the party, if available. Example+1 123-567-8989 emailAddressstring The email address of the party, if available. Exampletest@test.com namestring The name of the party, if available. ExampleTest User partyIdstring An identifier that is only required when speakersTimeline is provided. The partyId is used to recognize the speakers within the provided speakersTimeline. Example1 mediaChannelIdinteger (int32) 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) Minimum0.0Maximum1.0Example0 context Array of object (PartyUploadContext) A list of links to external systems such as CRM, Telephony System, Case Management, etc. object Links to external systems such as CRM, Telephony System, Case Management etc. Currently only Salesforce and Generic are supported. systemstring Required External system name. Currently only Salesforce and Generic are supported. Valid values[ "Salesforce", "HubSpot", "MicrosoftDynamic", "Generic" ]ExampleSalesforce objects Array of object (ExternalCrmPartyObject) List of objects within the external system object External object associated with the party objectTypestring Required Object Type. Valid only for non-company parties. e.g. Lead. Valid values[ "Lead", "Contact", "Account", "Opportunity", "User", "Lead,Contact" ]ExampleContact objectIdstring Required Object ID. For Salesforce both case-sensitive and case-insensitive formats are supported. Example0013601230sV7grAAC fields Array of object (CrmPartyContextField) Object fields. Intended for future use only. object External object data namestring Field name Examplename valueobject Object value ExampleGong Inc. userIdstring The user ID of the participant within the Gong system, if the participant is a user. Example234599484848423 directionstring Required Whether the call is inbound (someone called the company), outbound (a rep dialed someone outside the company), or a conference call. Valid values[ "Inbound", "Outbound", "Conference", "Unknown" ] dispositionstring The disposition of the call. The disposition is free text of up to 255 characters. Min length0Max length255ExampleNo Answer context Array of object (CallUploadContext) A list of references to external systems such as CRM, Telephony System, Case Management, etc. object Links to external systems such as CRM, Telephony System, Case Management etc. Currently only Salesforce and Generic are supported. systemstring Required External system name. Currently only Salesforce and Generic are supported. Valid values[ "Salesforce", "HubSpot", "MicrosoftDynamic", "Generic" ]ExampleSalesforce objects Array of object (ExternalCrmCallObject) List of objects within the external system. Note: Multiple opportunities/deals belonging to the same account are not supported. object External object associated with the call objectTypestring Required Object Type. e.g. Account. Valid values[ "Opportunity", "Account", "Lead", "Contact", "User", "Opportunity,Account" ]ExampleAccount objectIdstring Required Object ID. For Salesforce both case-sensitive and case-insensitive formats are supported. Example0013601230sV7grAAC fields Array of object (ContextField) Object fields. Intended for future use only. object External object data namestring 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. Examplename valueobject Field value ExampleGong Inc. customDatastring Optional metadata associated with the call (represented as text). Gong stores this metadata and it can be used for troubleshooting. ExampleOptional data speakersTimelineobject (SpeakersTimeline) The audio recording speech segments (who spoke when). Note that speakersTimeline and mediaChannelId are mutually exclusive, when providing speakersTimeline - mediaChannelId will not be used. preciseboolean 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. Exampletrue speechSegments Array of object (SpeechSegment) The audio recording speech segments (who spoke when). object The audio recording speech segments (who spoke when). fromTimeinteger (int32) Required The start time of the segment in milliseconds from the beginning of the call. Minimum0.0Example5100 toTimeinteger (int32) Required The end time of the segment in milliseconds from the beginning of the call. Minimum0.0Example24000 partyIds Array of string Required 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. Example[ "1" ]string Example["1"] meetingUrlstring The URL of the conference call by which users join the meeting Examplehttps://www.conference.com/john.smith callProviderCodestring 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. Exampleclearslide downloadMediaUrlstring The URL from which Gong can download the media file. The URL must be unique, the audio or video file must be a maximum of 1.5GB. The 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). If you provide this URL, you should not perform the 'Add call media' step. Examplehttps://upload-server.com/sample-call.mp3 workspaceIdstring Optional workspace identifier. If specified, the call will be placed into this workspace, otherwise, the default algorithm for workspace placement will be applied. Example623457276584334 languageCodestring The language code the call should be transcribed to. This 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. Valid 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 flowContextobject (FlowContext) The Id for the task the call should be associated with taskIdstring A task identifier Example714366367493425 primaryUserstring Required The Gong internal user ID of the team member who hosted the call. Example234599484848423 Responses200 Successful response object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw callIdstring New call ID Example7782342274025937895 400 Malformed request object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw errors Array of string Error messages. Example[ "An error has occurred" ]string 401 Access denied object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw errors Array of string Error messages. Example[ "An error has occurred" ]string 409 Conflict, e.g. recording is not enabled for the primary user object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw errors Array of string Error messages. Example[ "An error has occurred" ]string 429 API request limit exceeded HeadersRetry-AfterintegerNumber of seconds to wait before making a new request. object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw errors Array of string Error messages. Example[ "An error has occurred" ]string 500 Failed to complete the operation due to an unexpected error object requestIdstring A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes. Example4al018gzaztcr8nbukw errors Array of string Error messages. Example[ "An error has occurred" ]string