Working with the Aptrinsic REST API
Welcome to the Aptrinsic API reference guide!
The Aptrinsic API will provide you with a programmatic (server based) method to access the users, accounts and events that have been captured on your Aptrinsic subscription.
The Aptrinsic API 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 Aptrinsic API is https://api.aptrinsic.com/v1 and currently exposes the below two endpoints:
|API Name||API Endpoint URL||Description|
|Users||/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=)
A few notes:
- Data Payload
- All API data (data & responses) is JSON encoded with UTF-8 as either a single JSON object or as a list of JSON objects.
- Authorization & 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 & DELETE)
- Resources are identified using URI’s.
- Rate Limiting
- Although there is no rate limiting currently in place, Aptrinsic will reach out to you if extreme API usage is detected.
- pageSize & scrollId
- As documented in the Aptrinsic Rest Swagger Doc, the default pageSize on get calls (i.e. /users & /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 Aptrinsic 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 & 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 Aptrinsic. 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 key holder may be able to gain access to your private customer data in Aptrinsic.
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 email@example.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 Aptrinsic REST API swagger documentation.
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.
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 & 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 \,
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):