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.

Upload CRM objects (/v2/crm/entities)

  • Updated on Nov 17, 2025
  • Published on Oct 19, 2025
  • 10 minute(s) read
Prev Next
Post
/v2/crm/entities

Inserts, updates, or deletes a CRM entity in Gong.

Gong searches for existing entities with the same ID, to determine whether the entity should be added or updated.

Ensure you have an authentication key and that you have registered your integration before uploading your CRM data.

When accessed using a bearer token, this endpoint requires the 'api:crm:upload' scope.

Request parameters

Query String parameters

Mandatory parameters are marked with a *.

Name Description Data Type
integrationId * Integration ID generated when creating the integration long
objectType * The object being uploaded. Options are (case-sensitive):
  • ACCOUNT
  • CONTACT
  • DEAL
  • LEAD
  • BUSINESS_USER
  • STAGE
 string
clientRequestId * A unique identifier sent by you to allow troubleshooting and to prevent repeated attempts to upload the same list of objects.
Valid characters: letters, numbers, dashes and underscores.		 string

Request Body

  • Content-Type should be multipart/form-data
  • Maximum payload size: 200 megabytes
Name Description Data Type
dataFile * The LDJSON file with the entity data to upload. A file should only contain objects of one entity type. Records that have multiple updates should be sent in separate files. Each JSON object should be on a separate line. file

CRM Entities

This section details the entities that can be uploaded to Gong

Business User

The CRM business user represents the Gong user in the CRM and is responsible for the relationship with the account and for creating opportunities and closing deals. Uploading business users enables Gong to associate CRM entities such as accounts and contacts with the relevant user in Gong and with their Gong activity, such as conversations.

Mandatory parameters are marked with a *.

To upload your business users to Gong, generate a JSON file with the following fields:

Name Description Data Type
objectId * The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used 		string
modifiedDate * The date and time the object was last modified in the CRM ISO-8601 datetime format, without milliseconds
isDeleted (Default: false) When true, the object is deleted from the database. boolean
url The full URL path to view this object in the CRM string (Qualified URI)
emailAddress * The business user's email address. Used to associate the Gong user with the CRM user. Not mandatory when isDeleted = true. string

Associating the Gong user with the CRM user

The CRM user is associated with the Gong user according to the email address. Each CRM deal contains an ownerId field, which is the CRM user ID.

To update an existing user:

  1. Delete the existing user by uploading the business user entity with isDeleted=true.
  2. In a new request, send the new user details with isDeleted=false, or send a different user with the same email address.

Account

The account object is an active customer in the CRM. Emails and calls in Gong are associated with this account object.

Mandatory parameters are marked with a *.

To upload your CRM accounts to Gong, generate a JSON file with the following fields:

Name Description Data Type
objectId * The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used 		string
modifiedDate * The date and time the object was last modified in the CRM ISO-8601 datetime format, without milliseconds
isDeleted (Default: false) When true, the object is deleted from the database boolean
url A full http URL to browse this object in the CRM string (Qualified URI)
name The account name.
Default value: "Account_#"+objectId		 string
domains The account's domain/s. When an activity can’t be associated with a contact, the participants domain is used to associate the activity to an account via the account domain in this field. string array

Contact

A contact in Gong is the contact associated with the account. Gong uses a contact to match an activity to the correct account.

Mandatory parameters are marked with a *.

To upload your CRM contacts to Gong, generate a JSON file with the following fields:

NameDescriptionData Type
objectId *The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used		string
modifiedDate *The date and time the object was last modified in the CRMISO-8601 datetime format, without milliseconds
isDeleted(Default: false) When true, the object is deleted from the database.boolean
urlA full http URL to browse this object in the CRMstring (Qualified URI)
accountIdThe ID of the account associated with the contact in the CRM. Used to associate an activity to an account once the activity has been associated with a contact.string
emailAddressThe contact's email address. Used to associate activities to a contact, based on the participants email. string
firstNameThe contact's first namestring
lastNameThe contact's last namestring
titleThe contact's titlestring
phoneNumberThe contact's phone number. Used to associate telephony system calls to a contact based on the call participant's phone number.string

Deal

A deal in Gong is a qualified opportunity or contract in a specific account.

Mandatory parameters are marked with a *.

To upload your deals to Gong, generate a JSON file with the following fields:

NameDescriptionData Type
objectId *The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used		string
modifiedDate *The date and time the object was last modified in the CRMISO-8601 datetime format, without milliseconds
isDeleted(Default: false) When true, the object is deleted from the database.boolean
urlA full http URL to access this object in the CRMstring (Qualified URI)
accountIdThe ID of the account the deal is associated with in the CRM.
Note: Deals without an accountId will not appear in Gong		string
ownerIdThe ID of the deal owner in the CRM. This ID should be the same as the business user objectId so the deal can be associated with the correct Gong user.
Note: Deals without an ownerId will not appear in the deal board in Gong. 		string
nameThe deal name
Default value: Deal_# + objectId		string
createdDateThe date and time the deal was created in the CRM.ISO-8601 datetime without milliseconds
closeDateThe date the deal closed or is expected to close.
Note: Deals without a closeDate will not appear in the deal board in Gong.		string
statusThe deal status. Possible values are:
  • WON
  • LOST
  • OPEN

Default value: OPEN		string
stageThe stage the deal is in. If empty, it will not always be possible to associate activities with deals.
Must be the same as one of the values in the objectId field in the stages object		string
amountThe deal amount in the currency unit. Companies set their default currency in the Company Settings page. All amounts should be sent in this currency. If your deal is in a different currency, convert the deal amount to the currency defined in the Company Settings page.
Default value: 0		currency

Lead

A Lead is a potential customer, who may not yet be associated with an account. If conversations can't be associated with a contact, Gong then checks to see whether there is a relevant lead to associate with the conversation.

Mandatory parameters are marked with a *.

To upload your leads to Gong, generate a JSON file with the following fields:

NameDescriptionData Type
objectId *The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used		string
modifiedDate *The date and time the object was last modified in the CRMISO-8601 datetime format, without milliseconds
isDeleted(Default: false) When true, the object is deleted from the database.boolean
urlA full http URL to browse this object in the CRMstring (Qualified URI)
emailAddress The lead's email address. Used to associate activities to a lead, based on the participants email. string
firstName The lead's first namestring
lastName The lead's last namestring
titleThe lead's titlestring
phoneNumber

The lead's phone number. Used to associated telephony system calls to a lead based on the call participant's phone number.

string
convertedToDealIdThe deal ID in the CRM. Relevant if the lead is converted to a dealstring
convertedToContactIdThe contact ID in the CRM the lead was converted to. Relevant if the lead is converted to a contactstring
convertedToAccountIdThe account ID in the CRM the lead was converted to. Relevant if the lead is converted to an accountstring

Stage

The list of stages the deal can be in, in the CRM. Stages are set to be active or inactive so that if you want to delete them, the stage is still associated with existing deals in that stage but will not be available for new deals.

Mandatory parameters are marked with a *.

To upload your stages to Gong, generate a JSON file with the following fields:

NameDescriptionData Type
objectId *The CRM unique ID for the object.
Note: objectId can have a maximum of 64 characters and can have the following characters:
  • alpha numeric characters and a "-"
  • a valid email address
No other special characters can be used		string
name *The display name for the stagestring
isActiveWhen true, sets the stage to active in Gong. When false, sets the stage to inactive in Gong.
Default value: true		boolean
sortOrderThe order of the stage in the sales process (starting from 1). The stages are displayed according to this order. If two stages have the same sort order they will be displayed one after another.
Default value: 1		integer

Example

Upload Business User account

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=BUSINESS_USER
{"objectId": "user1_Id_In_The_CRM", "emailAddress": "john.doe@acme.com", "modifiedDate": "2019-01-03T23:45:57+01:00"}
// remove user mapping for user user2_Id_In_The_CRM
{"objectId": "user2_Id_In_The_CRM", "isDeleted": true, "emailAddress": "john.taylor@acme.com", "modifiedDate": "2019-01-03T23:45:57+01:00"}

Upload Stage example

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=STAGE
{"objectId": "discovery", "name": "Discovery", "isActive": true, "sortOrder": 1}
{"objectId": "won", "modifiedDate": "2019-01-03T23:45:57+01:00", "name": "Closed Won", "isActive": true, "sortOrder": 5}

Upload Account example

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=ACCOUNT
// account with additional field
{"objectId": "5ybyh6n6n65", "modifiedDate": "2019-01-03T23:45:57+01:00", "url": "https://crm.com/accounts/5ybyh6n6n65", "name": "PBR", "domains": ["pbr.com", "pbr.gov"], "type": "Investor"}
// remove account gfjhty756th from Gong
{"objectId": "gfjhty756th", "modifiedDate": "2019-01-03T22:45:57Z", "name": "PBR", "domains": ["pbr.com", "pbr.gov"], "isDeleted": true}

Upload Contact example

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=CONTACT
{"objectId": "5zbwd7n5n65", "modifiedDate": "2019-01-03T23:45:57+01:00", "url": "https://crm.com/contacts/5zbwd7n5n65", "accountId": "5ybyh6n6n65", "emailAddress": "john.smith@acme.com", "firstName": "john", "lastName": "smith", "phoneNumber": "(912) 507-4395"}

Upload Lead example

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=LEAD
{"objectId": "4v5bt54t553", "modifiedDate": "2019-01-03T23:45:57+01:00", "url": "https://crm.com/leads/45k4j5j5k44", "emailAddress": "jane.doe@acme.com", "firstName": "Jane", "lastName": "Doe", "title": "VP Special Effects", "phoneNumber": "(912) 507-4395"}
// remove lead gf4543gf6th
{"objectId": "gf4543gf6th", "modifiedDate": "2019-01-03T22:45:57Z", "emailAddress": "john.smith@acme.com", "firstName": "John", "lastName": "Smith", "isDeleted": true}
// lead 63473hjg53h converted to account 6sjk47jf78d, contact 87grhn74hg6 and deal dkfj8dfgf87
{"objectId": "63473hjg53h", "modifiedDate": "2019-01-03T23:45:57+01:00", "emailAddress": "bob.smith@acme.com", "firstName": "Bob", "lastName": "Smith", "convertedToDealId": "dkfj8dfgf87", "convertedToContactId": "87grhn74hg6", "convertedToAccountId": "6sjk47jf78d"}

Upload Deal example

POST https://api.gong.io/v2/crm/entities?clientRequestId=1234&integrationId=6286478263646&objectType=DEAL
{"objectId": "8608553", "modifiedDate": "2022-02-04T18:24:59Z", "url": "http://crm.com/deals/8608553", "accountId": "5ybyh6n6n65", "ownerId": "5486951", "name": "Deal name", "createdDate": "2022-02-04T17:57:23Z", "closeDate": "2022-09-04", "status": OPEN, "stage": "discovery", "amount": 7000, "custom_field_1": "2022-02-04T17:57:23.000Z", "custom_field_2": null}

Uploading additional fields

If you defined additional fields using the /v2/crm/entity-schema API, include those fields in the JSON file.

Body parameters
object
dataFile
string (binary) Required

The CRM data file. You may attach files up to 200MB in size

Responses
201

Successfully uploaded the crm data.
Important: This API is asynchronous. A 201 response indicates that the file successfully uploaded to Gong and is pending processing. Use the clientRequestId to verify the status of the request by calling the GET /v2/crm/request-status endpoint.

object
requestId
string

A Gong request reference Id, generated for this request. Can be used for troubleshooting purposes.

Example4al018gzaztcr8nbukw
clientRequestId
string

The clientRequestId sent in the request - used to monitor the request process

ExampleclientRequest1
400

Malformed request

object
requestId
string

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
requestId
string

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

Client request id has already been used

object
requestId
string

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

Headers
Retry-After
integer
Number of seconds to wait before making a new request.
object
requestId
string

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
requestId
string

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