Skip to main content
Gainsight Inc.

Work with the Gainsight PX REST API

This article explains how to configure the Gainsight PX REST API.

Overview

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.

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

API Summary

The base URL of each data center for Gainsight PX API is as follows: 

Gainsight PX API exposes the following endpoints:

  • Accounts
  • Admin
  • Engagement
  • Custom event
  • Email Event
  • EngagementViewEvent
  • FeatureMatchEvent
  • FormSubmitEvent
  • IdentifyEvent
  • LeadEvent
  • PageViewEvent
  • SegmentMatchEvent
  • SessionEvent
  • Feature
  • Localization
  • Segment
  • UserPreferences
  • Users

For more information on the list of endpoints and HTTP methods, refer to the Gainsight PX REST API Swagger documentation from the Additional Resources section.

Notes:

  • Data Payload
    • All API data (data and responses) is JSON encoded with UTF-8 as either a single JSON object or as a list of JSON objects.
  • Authorization
    • Authorization and access to the API is managed via API Keys (see below)
  • Errors
    • Errors are returned with error code and JSON response
  • HTTP
    • All Requests are sent using HTTPS
    • Methods exposed are based on HTTP Verbs (GET, POST and DELETE)
    • Resources are identified using URI’s.
  • Rate Limiting
    • The rate limit for public REST APIs is around 200 requests per second and 1 Million requests per day. Gainsight PX Support will reach out to you if extreme API usage is detected.
  • pageSize and scrollId
    • As documented in the Gainsight PX REST Swagger document, the default pageSize on get calls (i.e. /users and /accounts) is 25.  You can change the pageSize by adding a pageSize parameter to your URL (i.e. /users?pageSize=100) with max pageSize=1000.
    • Use the returned scrollId to make a request for the next page of results (i.e. /users?pageSize=100&scrollId=XXXXXXX)
    • Scroll until the returned result list is less than the requested size. Do not depend on the scrollId becoming null, in some cases it does not be null even though the last page of results is returned.

  • Case Sensitivity
    • Case sensitivity is enforced when making a call to get user/account by id.  Therefore, .../users/id=nora@example.com will not find a user whose id is Nora@example.com
    • Case sensitivity is not enforced when using filters. For example, ../users/filter=id==nora@example.com; will find a user whose id is Nora@example.com.

Generate API Key 

You need an API Key to access the Gainsight PX REST API. 

To generate an API key: 

  1. Navigate to Administration > REST API to access the API Keys page.

  2. Click New API Key. The New API Key window appears. 

  3. Enter the following details:

    1. Name: Enter a name for API Key. 

    2. Description: Enter a description.

    3. Permissions:  Configure the following permissions.

      1. Read: This permits to read PX data via GET API calls. 

      2. Write: This permits to edit and update PX data via PUT API call, and delete PX data via DELETE API calls. 

      3. Production Launch: This access permits to launch engagements in production. 

  4. Click Generate.

New API KEY1.png

IMPORTANT:  

  • Save this key in a safe location as there is no way to view the key again in Gainsight PX.  If you lose the key, you need to create a new key and replace your code’s authorization area with the new key’s value.
  • Gainsight strongly recommends that you never share the key outside of your organization, otherwise, the keyholder may be able to gain access to your private customer data in Gainsight PX.
  • To use your API Key, simply add it to the X-APTRINSIC-API-KEY header on your REST API requests.
  • A common way to test REST API requests is to use a tool like Postman.  
  • For more information on the specific endpoints and fields available, refer the Gainsight PX REST API swagger documentation from the Additional Resources section.
  • You can download a sample code that you can be imported into postman for testing all the available endpoints and API calls, from here

Using Filters

The filter query string parameter restricts the data returned when making a list API call to the users or accounts endpoint.  When you use the filter parameter, you supply a dimension you want to filter on, followed by the filter expression.

Go to Administration > Attributes to see the list of filter dimensions available.

Filtered queries restrict the rows that get included in the result. Each row in the result is tested against the filter: if the filter matches, the row is retained, and if it doesn't match, the row is dropped.

  • URL Encoding: The client libraries automatically encode the filter operators. However, if you make requests directly to the protocol, you must explicitly encode filter operators as indicated in the table below.
  • Filtering priority: Filtering occurs before any dimensions are aggregated so that the returned metrics represent the total for only the relevant dimensions.

Filter Syntax

A single filter uses the form:

name operator expression

In this syntax:

  • name — the name of the dimension to filter on. For example, firstName will filter on the First Name.
  • operator — defines the type of filter match to use.
  • expression — states the values included in the results.

Filter Operators

There are two filter operators. The operators must be URL encoded in order to be included in URL query strings.

Operator Description URL Encoded Form Example
== Exact Match %3D%3D Returns record where the country name is Canada:
filter=countryName%3D%3DCanada
~ String matching with wildcard support for * and? %3D@ Returns records where the name contains gainsight:
filter=name~*gainsight*
!= Not equal %21%3D Returns records where name is not gainsight:
filter=name%21%3Dgainsight
< Less than %3C Returns records where createDate is less than 1/28/2019 2:57
filter=createDate%3C1548687466658
<= Less than or equal %3C%3D Returns records where createDate is less than or equal to 1/28/2019 2:57
filter=createDate%3C%3D1548687466658
> Greater than %3E Returns records where createDate is greater than 1/28/2019 2:57
filter=createDate%3E1548687466658
>= Greater than or equal %3E%3D Returns records where createDate is greater than or equal to 1/28/2019 2:57
filter=createDate%3E%3D1548687466658
!~ Not matching / Not contains %21%7E Returns records where emailid does not match or does not contain gainsight.com:
filter=email!~*gainsight.com*

Filter Expressions

Following are a few of the key points for filter expressions:

  • URL-reserved characters: Characters such as commas, equal signs, semi-colons, ampersands, and question marks must be URL-encoded in the usual way. Client libraries take care of this for you, so you need to worry about this encoding only if you are making direct calls to the protocol.

    The full list of reserved characters is: ! * ' ( ) ; : @ & = + $ , / ? % # [ ]

  • Reserved characters: The comma and backslash must be backslash-escaped when they appear in an expression.

    • backslash \\
    • comma \,

Note: Make sure you escape backslashes before commas, to avoid double escaping.

  • Date filters: When using the event-related APIs for listing event data such as custom events, identify events etc., a date filter can be in one of the formats:
    • epoch milliseconds (e.g. 1626112614000) 
    • ISO Instant format (e.g. 2021-07-12T17:56:54Z).

An example of fetching custom events within a date range using the ISO format is:

https://api.aptrinsic.com/v1/events/custom?filter=date>2021-07-12T17:56:54Z;date<2021-07-16T19:08:58Z

For the custom event list only, if integrating with a system that requires the use of separate parameter names for date range filters, instead of passing the date range values as filters, use the optional dateRangeStart and dateRangeEnd parameters.

Example:

https://api.aptrinsic.com/v1/events/custom?dateRangeStart=2021-07-12T17:56:54Z&dateRangeEnd<2021-07-16T19:08:58Z

Combining Filters

Filters can be combined using OR and AND boolean logic.

OR logic

OR logic is achieved by providing multiple filter parameters (which translates into providing an array of filters in the client libraries).

Example: (each must be URL encoded)

Country code is either (US OR UK):

countryCode==US&filter=countryCode==UK

AND logic

AND logic is defined using a semicolon (;) inside the filter expression.

Example:

Country code is US AND city name is Cleveland:

filter=countryCode%3D%3DUS;cityName%3D%3DCleveland

Combining AND and OR logic

It's possible to combine AND and OR logic into a single expression.

Note: Each filter is evaluated individually before all filters are combined into an OR logical expression.

Example:

(Country code is US AND city name is Cleveland) OR ( country code is UK  AND city name is Cleveland):

filter=countryCode%3D%3DUS;filter=cityName%3D%3DCleveland &countryCode%3D%3DUK;filter=cityName%3D%3DCleveland

Sample API Calls

Click here to download a Postman collection file containing sample calls that you can use to query and test the Gainsight PX REST API. The Postman tool is used to test the PX APIs. To use the sample API calls, you must define a Postman variable apikey.  This variable must be set to the PX API key which you have generated. This API key is not the same as your Product API key. For more information on how to generate the API key, refer to the API keys section of this article. 

Additional Resources

Gainsight PX REST API swagger
  • Was this article helpful?