Skip to main content
Gainsight Inc.

User Preferences for Tracking and Engagement

ATTENTION: Documentation Updates are in Process
We are in the process of updating the screenshots, GIFs, and content to match the latest UX based on the Horizon Experience’s new look and feel. To learn more about the Horizon Experience in Gainsight PX, click here.

Overview

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

/user/preference

The syntax for the API is:

userPreferences
{
  "trackUsage" : true,
  "productUpdates" : true,
  "guidedTours" : true,
  "surveys" : true,
  "onboardingBot" : true
}

The following user preferences can be executed:

S.No. Preference Default Description
1 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.
2 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. 
3 guidedTours true Opted-in to see guided tours.
4 surveys true Opt-in to see the survey - NPS®/CES, CSAT.
5 onboardingBot true Opted-in for Bot assistance.

Access via REST API

Endpoint: User Preferences REST API

Headers

X-APTRINSIC-API-KEY: {apiKey}
Content-Type: application/json

Endpoint

http://api.aptrinsic.com/v1/user/preferences/{identifyId}

Model

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

Methods

GET

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

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

Rest API Key.png

PUT

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
}

 

  • 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

Examples

GET

Request
curl --request GET 'http://api.aptrinsic.com/v1/user/preferences/johndoe@example.com' \
--header 'X-APTRINSIC-API-KEY: aa8893cd-5cf8-493d-1780-fa199f19f005'
Response
Status: 200 OK
{
    "trackUsage": true,
    "productUpdates": false,
    "guidedTours": true,
    "surveys": null,
    "onboardingBot": null
}

PUT

Request
curl --request PUT 'http://api.aptrinsic.com/v1/user/preferences/johndoe@example.com' \
--header 'X-APTRINSIC-API-KEY: aa8893cd-5cf8-493d-1780-fa199f19f005' \
--header 'Content-Type: application/json' \
--data-raw '{
"trackUsage" : true,
"surveys" : false,
"onboardingBot" : false
}'
Response

Status: 204 No Content

References

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.

API Summary 

The base URL for the Gainsight PX API is https://api.aptrinsic.com/v1 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 list of all users (/users)

  • Get 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 list of all accounts  (/accounts)

  • Get 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.

NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld.
  • Was this article helpful?