User Preferences for Tracking and Engagement

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:

Overview
User Preferences Model
Access via REST API

User Preferences Model

/user/preference

The syntax for the API is:

userPreferences
{
    "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

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;
  Boolean trackEmailAnalytics;
}

Methods

GET

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

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, 
  "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

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,
    "trackEmailAnalytics": false,
}

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 from the Additional Resources section.

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