Gainsight PX Audience

Private Beta

Sync warehouse and Audience Builder membership to Gainsight PX as a Boolean custom user attribute.

8 minute read

The Gainsight PX Audience destination is in Private Beta.
Reach out to Customer Success to enable it for your workspace.

Gainsight PX is a product experience platform for product analytics and in-app engagement. Gainsight PX Audience keeps a Boolean custom user attribute in Gainsight PX in sync with an audience: the attribute is true while a user is in the audience and false after they leave. You can then target the attribute in Gainsight PX engagements and segments.

Gainsight PX Audience is separate from the Event Stream Gainsight PX destination.
Use Gainsight PX to send identify, track, and other Event Stream traffic.
Use Gainsight PX Audience for Reverse ETL and Audience Builder membership syncs.

Prerequisites

Do the following in Gainsight PX before you connect the destination:

Create a Boolean custom user attribute. Go to Administration > Attributes > User, create an attribute of type Boolean, and make sure it’s enabled. Note its API name — it’s case-sensitive. The Gainsight PX API can’t create attributes, so RudderStack can’t create it for you.
Create a REST API key. Go to Administration > REST API and create a key with Read and Write permission. Setup validation reads your attribute definitions; syncs write user attributes.
Find your data center. Match the host of your Gainsight PX URL:

Gainsight PX URL	Data center
`app.aptrinsic.com`	`US`
`app-eu.aptrinsic.com`	`EU`
`app-us2.aptrinsic.com`	`US2`

Confirm the users exist in Gainsight PX. The destination only updates existing users, matched on their Gainsight PX user ID (identifyId). Ask your data team which warehouse column holds that ID.

How membership is written to Gainsight PX

Each row is sent as one PUT /v1/users/update request that sets the attribute on the user whose identifyId matches the mapped column:

Action	Attribute value
Insert or update	`true` (the user is in the audience)
Delete	`false` (the user left the audience) Leaving the audience sets the attribute to `false`. It does not remove the attribute from the user.

Note that:

The update merges into the user profile. Other fields and custom attributes are kept.
identifyId is trimmed but otherwise sent as is. It is case-sensitive in Gainsight PX, so User-1 and user-1 are two different users.
If a user doesn’t exist in Gainsight PX, a join (true) is aborted for that row and counted as a failed record. With Retry failed records on (the default), the row is sent again on every following incremental run until it succeeds. With it off, the row is sent again only when it changes in the source or on a full sync. A leave (false) for an unknown user counts as success, since that user isn’t a member anyway.
Failed rows show the error message returned by Gainsight PX in the sync report.

Limitations

Limitation	Details
No user creation	Users are never created or deleted in Gainsight PX. Members who are not yet Gainsight PX users are reported as failed rows until they exist in Gainsight PX.
One request per row	Gainsight PX has no bulk user endpoint, so every row is a separate request. Gainsight PX limits its REST API to about 200 requests per second and 1 million requests per day per subscription, shared by every connection and integration on that subscription. Rows for users not in Gainsight PX are aborted, and with Retry failed records on, they are sent again on every run, so each attempt counts against the same limits. Size your syncs and schedules accordingly.
Full sync leaves stale `true` values	A full sync (Reset History and Full Sync) sets the attribute to `true` for everyone currently in the audience, but never sets it to `false` for anyone who left the audience before that run. Those users keep `true` until they re-enter and leave the audience again. Changing the column mapped to `identifyId` also runs a full sync. Avoid full syncs unless you accept this.
Attribute is fixed after creation	You can’t change the attribute API name once the connection exists. To use a different attribute, create a new sync.
Values stay after you disconnect	Disabling or deleting the connection makes no call to Gainsight PX. Attribute values stay as last written, and the attribute keeps using one of your subscription’s limited custom attribute slots until you delete it in Gainsight PX.
Users outside the source	Only users that the source has returned are written. Other users keep whatever value the attribute already has.
Recently deleted users	Gainsight PX restores a user deleted within the last 7 days when that user is written. A user you deleted in Gainsight PX who then leaves the audience is restored with the attribute set to `false`.

Troubleshooting

When you create a connection, RudderStack checks your account and attribute against Gainsight PX. If the check fails, the form shows one of these messages:

Message	Fix
`Gainsight PX has no user attribute with this API name. Create it under Administration › Attributes › User, or check the spelling; API names are case-sensitive.`	Create the attribute in Gainsight PX, or correct the API name. Copy the API name, not the display name, and match its case.
`This Gainsight PX attribute is not a Boolean. Use a Boolean custom user attribute.`	Create a new attribute of type Boolean and use its API name.
`This Gainsight PX attribute is disabled. Enable it under Administration › Attributes › User.`	Enable the attribute in Gainsight PX.
`This is a built-in Gainsight PX attribute. Use a custom user attribute.`	Use a custom attribute you created, not a Gainsight PX default attribute.
`Gainsight PX rejected the API key. Check the key and the data center.`	Check the REST API key in the account, and that the data center matches your Gainsight PX URL. A key used against the wrong data center is rejected the same way as a wrong key.
`The Gainsight PX API key lacks Read permission.`	Edit the key in Gainsight PX (Administration > REST API) and grant Read and Write permission.
`Gainsight PX is rate limiting requests. Try again in a minute.`	Wait and save again. If it persists, check other integrations using the same subscription.
`Gainsight PX returned an error (<status>). Try again later.`	A temporary Gainsight PX error. Save again later.
`Map exactly one column to identifyId.`	Map a single warehouse column to `identifyId`.
`Enter the attribute API name: letters, numbers and underscores, up to 200 characters.`	Remove any other character from the API name and keep it to 200 characters or fewer.
`The Gainsight PX account has an unsupported data center. Use US, EU or US2.`	Edit the account and select `US`, `EU`, or `US2`.
`The Gainsight PX account is missing its API key or data center.`	Edit the account and re-enter the REST API key and data center.

During a sync, rows can fail with these errors:

Error	Fix
`No identifyId mapped`	The mapped column is empty or missing for this row. Fix the data in your warehouse.
`Invalid identifyId`	The mapped column isn’t a string or number. Map a column that holds the Gainsight PX user ID.
An error from Gainsight PX that the user wasn’t found	The user doesn’t exist in Gainsight PX yet, or the mapped column isn’t the Gainsight PX `identifyId`. The row is aborted. With Retry failed records on (the default), it is sent again on every run and succeeds once the user exists. With it off, it is sent again only when the row changes in the source or on a full sync.
An error from Gainsight PX that the attribute doesn’t exist or isn’t enabled	The attribute was deleted or disabled in Gainsight PX after the connection was set up. Re-enable it, or create a new sync with another attribute.
An authentication or permission error from Gainsight PX	The API key was revoked or lost Write permission. Update the key in the account.

FAQ

Where can I find the Gainsight PX REST API key?

In Gainsight PX, go to Administration > REST API. Create a key with Read and Write permission. Keys are per subscription.

How is Gainsight PX Audience different from the Gainsight PX destination?

	Gainsight PX (Event Stream)	Gainsight PX Audience
Typical use	Identifies, tracks, and other events	Audience and Reverse ETL membership
Gainsight PX surface	Events, user and account properties	One Boolean custom user attribute per sync
Sync mode	Not applicable (streaming)	Mirror only

Why are some rows failing every run?

Those users don’t exist in Gainsight PX, or the column mapped to identifyId doesn’t hold the Gainsight PX user ID. Gainsight PX Audience never creates users, so these rows are aborted and reported as failed records.

With Retry failed records on (the default), each of these rows is sent again on every run and succeeds once the user exists in Gainsight PX — for example, after their first login tracked by the Gainsight PX tag. With it off, a row is sent again only when it changes in the source or on a full sync. Check the failed rows in the sync report.

Can I reuse one Gainsight PX account across syncs?

Yes. One account can back many syncs. Give each sync a different attribute so membership flags don’t overwrite each other.

Does leaving the audience remove the attribute in Gainsight PX?

No. Leaving sets the attribute to false. Gainsight PX doesn’t let the attribute be cleared, and the attribute stays on the user so you can still target users who are not in the audience.