This article explains how to configure the Gainsight PX Rest API.
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).
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|
For more information on a full list of endpoints and HTTP methods, refer to the Gainsight PX REST API Swagger doc from the Additional Resources section.
A few 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 and access to the API is managed via API Keys (see below)
- Errors are returned with error code and JSON response
- 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
- Although there is no rate limiting currently in place, Gainsight PX will reach out to you if extreme API usage is detected.
- pageSize and scrollId
- As documented in the Gainsight PX Rest Swagger Doc, 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)
- Case Sensitivity
- Case sensitivity is enforced when making a call to get user/account by id. Therefore, .../email@example.com will not find a user whose id is Nora@example.com
- Case sensitivity is not enforced when using filters. For example, ../firstname.lastname@example.org; will find a user whose id is Nora@example.com.
You’ll need an API Key to access the Gainsight PX REST API. Navigate to Administration > REST API to access the API Keys page.
Click on New API Key. After you enter a name, description and set the permissions, click on the Create & View button to see the API Key.
- Save this key in a safe spot as there will be NO WAY to see the key again in Gainsight PX. If you lose the key, you will need to create a new key and replace your code’s authorization area with that new key’s value.
- 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 authorization 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.
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.
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.
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:
|~||String matching with wildcard support for * and?||%3D@||Returns records where the name contains gainsight:
|!=||Not equal||%21%3D||Returns records where name is not gainsight:
|<||Less than||%3C||Returns records where createDate is less than 1/28/2019 2:57
|<=||Less than or equal||%3C%3D||Returns records where createDate is less than or equal to 1/28/2019 2:57
|>||Greater than||%3E||Returns records where createDate is greater than 1/28/2019 2:57
|>=||Greater than or equal||%3E%3D||Returns records where createDate is greater than or equal to 1/28/2019 2:57
There are a couple of important rules 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, in order to avoid double escaping.
Filters can be combined using OR and AND boolean 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):
AND logic is defined using a semicolon (;) inside the filter expression.
Country code is US AND city name is Cleveland:
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.
(Country code is US AND city name is Cleveland) OR ( country code is UK AND city name is Cleveland):
Sample API Calls
This section shows examples of API calls that you can use to query the Gainsight PX REST API. These example calls allow you to test the Gainsight REST API. The Postman tool has been used to test the PX API's. To use the following 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 key section of this article.
Click this link to download a Postman collection file containing sample calls for the Gainsight PX API.
|Gainsight PX REST API swagger|