Skip to main content
Gainsight Inc.

User Preferences for Tracking and Engagement

This article explains the new user-preferences model and contains different sections.


Gainsight PX sends user engagements, tracks and analyzes user activities, and stores user data. However, if your customers would like to opt-out from receiving engagements or activity/data tracking, you can honor the user preferences via API calls.

This article explains the new user-preferences model and contains the following sections:

User Preferences Model


The syntax for the API is:

    "trackUsage": "track_usage",
    "productUpdates": "product_updates",
    "guidedTours": "guided_tours",
    "surveys": "surveys",
    "onboardingBot": "onboarding_bot", 
    "trackEmailAnalytics": "track_email_analytics" 

The following user preferences can be executed:

Preference Default Description
trackUsage True

Opted-in for the usage data in the analytics store to be tracked for the usage analysis. However, PX continues storing the session-level data and user profile in-memory to support critical in-app messaging. 

Note: If users opt-out of having their analytics tracked, PX will not store any session-level data. Therefore, the last seen or session-initialized data cannot be viewed. However, they can still be targeted with specific engagements.

productUpdate True Opted-in to see the product updates. 
Note: Users who have opted out of other In-App Messaging, will still be able to get important updates/ notifications such as COVID-19 and/or maintenance notifications. 
guidedTours True Opted-in to see guided tours.
surveys True Opt-in to see the survey - NPS®/CES, CSAT.
onboardingBot True Opted-in for Bot assistance.
trackEmailAnalytics True Users who have opted-in allow PX to track their Email activities, while opting-out prevents tracking of open and click events. However, PX still tracks unsubscribe, bounce, deferred, delivered, dropped, and processed events.

Access via REST API

Endpoint: User Preferences REST API


Content-Type: application/json



class UserPreferences {
  Boolean trackUsage;
  Boolean productUpdates;
  Boolean guidedTours;
  Boolean surveys;
  Boolean onboardingBot;
  Boolean trackEmailAnalytics;



Return UserPreferences object. If the field is not set - return null

Return trackEmailAnalytics object, which is by default set to true, unless opted out by the user.

API Key required permission: User Read/Write (Navigate to Administration > Rest API > New API Key)

API Key.jpg


Set UserPreferences object (sent in body)

The fields are optional so it’s possible to provide only those that need to be updated. If the user had preferences set earlier, override only the requested fields.

Body in JSON format:
  "trackUsage" : false,
  "productUpdates" : true,
  "guidedTours" : null,
  "surveys" : null,
  "onboardingBot" : false, 
  "trackEmailAnalytics": false,
  • Valid field values: true, false, null.
    Note: null value won’t override any other
  • API Key required permission: User Write

Response status codes

  • 200 - Success (only for GET)
  • 204 - Updated (only for PUT)
  • 400 - Bad request
  • 401 - Unauthorized or bad API Key
  • 403 - Access denied
  • 404 - User not found by identify id
  • 429 - Rate limit exceeded



curl --request GET '' \
--header 'X-APTRINSIC-API-KEY: aa8893cd-5cf8-493d-1780-fa199f19f005'
Status: 200 OK
    "trackUsage": true,
    "productUpdates": false,
    "guidedTours": true,
    "surveys": null,
    "onboardingBot": null,
    "trackEmailAnalytics": false,


curl --request PUT '' \
--header 'X-APTRINSIC-API-KEY: aa8893cd-5cf8-493d-1780-fa199f19f005' \
--header 'Content-Type: application/json' \
--data-raw '{
"trackUsage" : true,
"surveys" : false,
"onboardingBot" : false

Status: 204 No Content


The Gainsight PX API provides you with a programmatic (server-based) method to access the users, accounts and events that have been captured on your Gainsight PX subscription.

IMPORTANT: Gainsight PX is an industry-standard REST-ful API you use to perform most standard CRUD (Create, Read, Update, Delete) operations on exposed endpoints (i.e. User, Account). For more information, refer to the Work with the Gainsight PX REST API article from the Additional Resources section.

API Summary 

The base URL for the Gainsight PX API is and currently exposes the below two endpoints:

API Name API Endpoint URL Description
User /users
  • Create (post) and update (put) a user

  • Get information on a single user (/users/id=)

  • Get the list of all users (/users)

  • Get the list of all users with filter (/users?filter=)

Accounts /accounts
  • Create (post) and update (put) an account

  • Get information on a single account (/accounts/id=)

  • Get the list of all accounts  (/accounts)

  • Get the list of all accounts with filter (/accounts?filter=)

For more information about the full list of endpoints and HTTP methods, refer to the Work with the Gainsight PX REST API article from the Additional Resources section.

Additional Resources

Work with the Gainsight PX REST API
NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld.