Gainsight

Sync data from your warehouse to Gainsight. Keep your Gainsight Company records, Person records, and Custom Objects enriched with the latest customer attributes from Zeotap.

Prerequisites

A Gainsight NXT account with API access enabled
A Gainsight REST API access key (generated by a Gainsight Admin)
Your Gainsight instance domain (e.g., mycompany.gainsightcloud.com)

Authentication

Gainsight uses a non-expiring API access key for authentication.

Generating an Access Key

Log in to your Gainsight instance as an administrator
Navigate to Administration > Integrations > Connectors 2.0
Click API Keys and generate a new key
Copy the access key
Paste the access key into the Access Key field in Zeotap

The access key does not expire and provides access to all Gainsight REST APIs.

Configuration

Field	Type	Required	Description
Gainsight Domain	Text	Yes	Your Gainsight instance domain (e.g., `mycompany.gainsightcloud.com`). Do not include `https://` or trailing slashes.

Target Settings

Field	Type	Required	Description
Object Type	Select	Yes	The Gainsight object to sync to: Company, Person, or Custom Object
Custom Object Name	Text	Conditional	The API name of the custom object (e.g., `MyObject__gc`). Required when Object Type is Custom Object.
Lookup Keys	Text	No	Comma-separated field names used to identify existing records for update and upsert (e.g., `Name` or `Email`). Maximum 3 keys. Not applicable for Person objects.

Supported Operations

Sync Modes

Mode	Supported
Upsert	Yes
Insert	Yes
Update	Yes
Mirror	—

Audience Sync Modes

Mode	Supported
Add	—
Remove	—
Mirror	—
Upsert	—

Gainsight does not have a list or audience membership concept, so audience sync modes are not supported. Use standard sync modes to push data to Gainsight objects.

Features

Field Mapping: Yes
Schema Introspection: No

Required Mapping Fields

Object	Required Fields
Company	`Name`
Person	`Email`
Custom Object	None (fields depend on object definition)

Default Destination Fields

Company: Name, Industry, ARR, Employees, Stage, Status, RenewalDate

Person: Email, FirstName, LastName

How It Works

Company and Custom Object Syncs

Zeotap sends records to Gainsight in batches of up to 50 records per API call:

Insert mode: Records are sent via POST /v1/data/objects/{objectName}. Each record is created as a new entry.
Update mode: Records are sent via PUT /v1/data/objects/{objectName}?keys={lookupKeys}. Existing records matching the lookup keys are updated.
Upsert mode: Records are sent via the Update endpoint. Gainsight matches records by the configured lookup keys and updates them. If no lookup keys are configured, Name is used as the default.

Person Syncs

Person records are sent individually to the Gainsight People API via PUT /v1/peoplemgmt/v1.0/people. This endpoint performs a native upsert by email address — if a person with the given email exists, they are updated; otherwise, a new person record is created.

Error Handling

Per-record errors: When individual records fail (e.g., validation errors), Zeotap logs the error details and continues processing remaining records in the batch.
Rate limiting: Zeotap retries requests with exponential backoff when Gainsight returns HTTP 429 (Too Many Requests) or 5xx server errors.
Batch failures: If an entire batch fails, the error is recorded and subsequent batches continue processing.

Rate Limits

Gainsight enforces the following API rate limits:

Limit Type	Value
Synchronous API calls	100 per minute
Daily API calls	50,000 per day
Records per API call	50 (Company / Custom Object)
Person API	1 record per call (synchronous)

Zeotap automatically handles rate limiting with retries and backoff. For large syncs, consider scheduling during off-peak hours.

Best Practices

Configure lookup keys for update and upsert modes to ensure Gainsight can match existing records. Use unique fields like Name for companies or custom identifiers for custom objects.
Use the Person object for contact data — the People API provides native upsert by email, making it the most reliable sync path.
Keep batch sizes manageable — Gainsight’s 100 calls/minute limit means large datasets should be synced with appropriate scheduling.
Validate field names before syncing — Gainsight field names are case-sensitive. Ensure your field mappings match the exact field names in your Gainsight object schema.

Troubleshooting

Authentication failed: invalid access key

Verify that your access key is correct and has not been revoked. Generate a new key in Administration > Integrations > Connectors 2.0 > API Keys.

Domain not reachable

Ensure the Gainsight Domain is entered correctly without https:// or trailing slashes. The domain should look like mycompany.gainsightcloud.com.

Records not updating (no match found)

When using update or upsert mode, Gainsight matches records using the configured lookup keys. Ensure:

The lookup key fields exist in the target object
The values in your source data match existing records
You have not exceeded the maximum of 3 lookup keys

Custom object name not recognized

Custom object API names in Gainsight typically end with __gc (e.g., MyObject__gc). Verify the exact API name in Administration > Data Management > Objects.

Rate limit errors (HTTP 429)

Zeotap retries rate-limited requests automatically. If you consistently hit rate limits, reduce sync frequency or schedule syncs during off-peak hours. Gainsight allows 100 synchronous API calls per minute and 50,000 per day.

Person records not syncing

The Person API requires an Email field in every record. Ensure your field mapping includes Email as a required mapping. Records without a valid email address will fail.

Field validation errors

Gainsight enforces field types strictly. Common issues:

Date fields must be in MM-DD-YYYY format
Dropdown fields must contain a valid picklist value
Number fields cannot contain non-numeric values

Check the error details in your sync run logs for the specific field and validation error.

Freshdesk Outreach