---
title: "Upload CRM objects"
slug: "upload-crm-objects-v2crmentities-1"
updated: 2025-11-17T08:10:53Z
published: 2025-11-17T08:12:09Z
---

> ## 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)

Post/v2/crm/entities<style>.public-api-info {    background: rgb(222, 235, 255);}.public-api-tip {    background: rgb(227, 252, 239);}.public-api-parameter {    background: rgba(9,30,66,0.08);}.public-api-note {    background: rgb(234, 230, 255);}.public-api-important {    background: rgb(255, 250, 230);}.public-api-critical {    background: rgb(255, 235, 230);}table, th, td {  border: 1px solid gray;  border-collapse: collapse;}th, td {  padding: 5px;}th {  text-align: left;}img {  border: 2px solid #D3D5D9;}</style>

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 <font color="red">*</font>.

| Name | Description | Data Type |
| --- | --- | --- |
| integrationId <font color="red">*</font> | Integration ID generated when creating the integration | long |
| objectType <font color="red">*</font> | The object being uploaded. Options are (case-sensitive): - ACCOUNT - CONTACT - DEAL - LEAD - BUSINESS_USER - STAGE | string |
| clientRequestId <font color="red">*</font> | 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 <font color="red">*</font> | 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | 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 <font color="red">*</font> | 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | 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) |
| accountId | The 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 |
| emailAddress | The contact's email address. Used to associate activities to a contact, based on the participants email. | string |
| firstName | The contact's first name | string |
| lastName | The contact's last name | string |
| title | The contact's title | string |
| phoneNumber | The 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | 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 access this object in the CRM | string (Qualified URI) |
| accountId | The ID of the account the deal is associated with in the CRM. **Note**: Deals without an accountId will not appear in Gong | string |
| ownerId | The 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 |
| name | The deal name Default value: Deal_# + objectId | string |
| createdDate | The date and time the deal was created in the CRM. | ISO-8601 datetime without milliseconds |
| closeDate | The date the deal closed or is expected to close. **Note**: Deals without a closeDate will not appear in the deal board in Gong. | string |
| status | The deal status. Possible values are: - WON - LOST - OPEN Default value: OPEN | string |
| stage | The 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 |
| amount | The 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | 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) |
| emailAddress | The lead's email address. Used to associate activities to a lead, based on the participants email. | string |
| firstName | The lead's first name | string |
| lastName | The lead's last name | string |
| title | The lead's title | string |
| phoneNumber | The lead's phone number. Used to associated telephony system calls to a lead based on the call participant's phone number. | string |
| convertedToDealId | The deal ID in the CRM. Relevant if the lead is converted to a deal | string |
| convertedToContactId | The contact ID in the CRM the lead was converted to. Relevant if the lead is converted to a contact | string |
| convertedToAccountId | The account ID in the CRM the lead was converted to. Relevant if the lead is converted to an account | string |

### 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 <font color="red">*</font>.

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

| Name | Description | Data Type |
| --- | --- | --- |
| objectId <font color="red">*</font> | 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 <font color="red">*</font> | The display name for the stage | string |
| isActive | When true, sets the stage to active in Gong. When false, sets the stage to inactive in Gong. Default value: true | boolean |
| sortOrder | The 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<select class='api-response-data' aria-label='Media type'><option value='8f5fbbaa-9524-46a3-932d-fd859f95108f'>multipart/form-data</option>
</select>object  dataFilestring  (binary)    Required

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

Responses201

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.

<select class='api-response-data' aria-label='Media type'><option value='f91ecd4c-606a-462b-99e4-d342f64daa57'>application/json</option>
</select>object  requestIdstring    

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

Example4al018gzaztcr8nbukw
clientRequestIdstring    

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

ExampleclientRequest1

400

Malformed request

<select class='api-response-data' aria-label='Media type'><option value='cb1a323c-3bb3-47ed-8343-4d5044cae977'>application/json</option>
</select>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

<select class='api-response-data' aria-label='Media type'><option value='2c485a3f-b670-4913-b4e1-877f196dbb85'>application/json</option>
</select>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

Client request id has already been used

<select class='api-response-data' aria-label='Media type'><option value='2cf821d9-1fcd-4f47-83a6-619b6cde041c'>application/json</option>
</select>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.
<select class='api-response-data' aria-label='Media type'><option value='fe4f9ee9-39ec-47b7-a77a-3c5bf1180a64'>application/json</option>
</select>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

<select class='api-response-data' aria-label='Media type'><option value='a0f4ff9d-2104-44b3-a0e5-b4e240ad9c29'>application/json</option>
</select>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