Working with the Aptrinsic REST API

Updated 3 months ago by Angelo Matheou

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

API Summary

The base URL for the Aptrinsic API is https://api.aptrinsic.com/v1 and currently exposes the below two endpoints:

API NameAPI Endpoint URLDescription
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=)


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

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

IMPORTANT:  

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

OperatorDescriptionURL Encoded FormExample
==Exact Match%3D%3DReturns record where the country name is Canada:
filter=countryName%3D%3DCanada
=@Contains Substring%3D@Returns record where the country name contains United:
filter=countryName%3D@United

Filter Expressions

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 \,
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 defined using a semicolon (;) inside the filter expression.

Example: (each must be URL encoded)

Country code is either (US OR UK):

countryCode==US;countryCode==UK

AND logic

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

Example:

Country code is US AND city name is Cleveland:

filter=countryCode%3D%3DUS&filter=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 AND logical expression.

Example:

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

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


How did we do?