Skip to main content
Gainsight Inc.

Work with the Gainsight PX REST API

Overview

Welcome to the Gainsight PX API reference guide!

The Gainsight PX API will provide 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). Gainsight PX REST API

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=)

Check out the Gainsight PX REST API Swagger doc for a full list of endpoints and HTTP methods.

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
    • 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
    • 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, .../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.

API Keys

You’ll need an API Key to access the Gainsight PX REST API. Navigate to Account Settings -> REST API (or click here) to access the API Keys page.

Click on the New “API Key” button.  After you enter a name, description and set the permissions, click on the Create and View button to see the API Key.

IMPORTANT:  

  1. 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.
  2. Never share the key outside of your organization, otherwise the key holder 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.  

Reach out to success@aptrinsic.com for a Postman collection file that you can import into Postman to test all of the available endpoints and API calls.

For more details on the specific endpoints and fields available, check out the Gainsight PX REST API swagger documentation.

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 Account Settings -> 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%3C1548687466658
>= 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

Filter Expressions

There are a couple of important rules for filter expressions:

  • URL-reserved characters — Characters such as and must be url-encoded in the usual way. Client libraries take care of this for you, so you only have to worry about this encoding if you are making direct calls to the protocol.
  • 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.

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

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. To learn more about how to generate the API key, refer to the API key section of this article. 

Sample API calls are as follows:

{
    "info": {
        "_postman_id": "08acdf86-3733-4fb7-890a-c25147588ab4",
        "name": "Gainsight PX REST API v1",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "Account",
            "item": [
                {
                    "name": "Delete Account",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "url": {
                            "raw": "{{apiUrl}}/v1/accounts/{{accountID}}",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "accounts",
                                "{{accountID}}"
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "List Accounts",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "url": {
                            "raw": "{{apiUrl}}/v1/accounts?sort=createDate",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "accounts"
                            ],
                            "query": [
                                {
                                    "key": "sort",
                                    "value": "createDate"
                                }
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Create Account",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"id\" : \"myId37\",\n  \"name\" : \"Public API Account 37\",\n  \"lastSeenDate\" : 1513360230,\n  \"dunsNumber\" : \"duns Number\",\n  \"industry\" : \"industry\",\n  \"numberOfEmployees\" : 1234,\n  \"sicCode\" : \"sic code\",\n  \"website\" : \"http://www.example.com\",\n  \"naicsCode\" : \"naics code\",\n  \"plan\" : \"plan\",\n  \"location\" : {\n    \"countryName\" : \"United States\",\n    \"countryCode\" : \"USA\",\n    \"stateName\" : \"Oregon\",\n    \"stateCode\" : \"OR\",\n    \"cityName\" : \"Portland\",\n    \"street\" : \"24511 NE Hawthorne Ave.\",\n    \"postalCode\" : \"97241\",\n    \"continentCode\" : \"NA\",\n    \"regionName\" : \"region\",\n    \"timeZone\" : \"PST\"\n  }\n}\n"
                        },
                        "url": {
                            "raw": "{{apiUrl}}/v1/accounts",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "accounts"
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Update Account",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "type": "text/javascript",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ]
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "type": "text/javascript",
                                "exec": [
                                    ""
                                ]
                            }
                        }
                    ],
                    "request": {
                        "method": "PUT",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n  \"customAttributes\" : {\n  \t\"numberOfProducts\": 0,\n  \t\"numberOfEvents\" : 0\n  }\n}\n"
                        },
                        "url": {
                            "raw": "{{apiUrl}}/v1/accounts/{{accountID}}",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "accounts",
                                "{{accountID}}"
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Get Account",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "url": {
                            "raw": "{{apiUrl}}/v1/users/{{accountID}}",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "users",
                                "{{accountID}}"
                            ]
                        }
                    },
                    "response": []
                }
            ]
        },
        {
            "name": "User",
            "item": [
                {
                    "name": "Get User",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "type": "text/javascript",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ]
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "type": "text/javascript",
                                "exec": [
                                    ""
                                ]
                            }
                        }
                    ],
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "X-APTRINSIC-API-KEY",
                                "value": "{{apiKey}}",
                                "description": "api key"
                            }
                        ],
                        "url": {
                            "raw": "{{apiUrl}}/v1/users/{{identifyID}}",
                            "host": [
                                "{{apiUrl}}"
                            ],
                            "path": [
                                "v1",
                                "users",
                                "{{identifyID}}"
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Delete User",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "6cf20c72-d0d2-4aba-a114-5244800f729d",
                                "exec": [
                                    "",
                                    "",
                                    "",
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "676de617-3284-47c7-b516-5b14a02a03be",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "DELETE",
                        "header": [
                            {
                                "key": "X-Requested-With",
                                "value": "XMLHttpRequest"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
  • Was this article helpful?