The TrueLoyal API is a RESTful API built on HTTP, uses the OAuth 2.0 protocol to authorize applications to access data on behalf of users, and the requests and responses are formatted according to the JSON:API specification.

The vast majority of our API endpoints require an OAuth 2.0 bearer token. In order to get one, you will first need to create an OAuth application:

• Sign in to TrueLoyal
• Click on your name or email on the top right corner
• Select Team Settings
• Choose API
• Click on the Add button
• Create your OAuth 2.0 application

Once done, you'll receive the client ID and secret you need to initiate the authorization flow.

We currently only support the authorization code flow so you will need to authenticate as a user. Our API tokens are short-lived but you will be provided a refresh token you can use to get a new access token when your token has expired.

You must provide the id_token provided when the user authorized your application as a query parameter in order to make changes to sensitive information such as their email, password, authentication factors, etc. The id_token is only valid for 15 minutes.

Should your id_token expire, you must redirect the user to the OAuth authorization URL above for the user to provide authorization again.

PATCH /v2/me?id_token=nHOoUfFHEm.pvgdGWlMz6X1mQvyY7ORPxFbIksmf6qz.srCyXxT2Fv HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Authorization: Bearer bbAo5OvKt5p7NlJ4PlMWpE87wrkxhiJDayIgHSyhGx92KmSOHf5UtvpGK14ARxYA

{
  "data": {
    "id": 1,
    "type": "user",
    "attributes": {
      "email": "support-advocacy@trueloyal.com"
    }
  }
}

You may customize which related resources are returned using the include request parameter. The value of the include parameter must be a comma-separated list of relationship paths. A relationship path is a dot-separated list of relationship names.

For instance, authentication factors could be requested with a user:

GET /v2/me?include=authentication_factors HTTP/1.1
Accept: application/vnd.api+json

In order to request resources related to other resources, a dot-separated path for each relationship name can be specified:

GET /v2/teams/1?include=tints.personalizations HTTP/1.1
Accept: application/vnd.api+json

Multiple related resources can be requested in a comma-separated list:

GET /v2/me?include=authentication_factors,teams HTTP/1.1
Accept: application/vnd.api+json

You may request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter. The value of the fields parameter must be a comma-separated list that refers to the name(s) of the fields to be returned.

For example:

GET /v2/teams/1/tints?include=personalizations&fields[tints]=name,status&fields[personalizations]=name,theme HTTP/1.1
Accept: application/vnd.api+json

We limit the number of resources returned in a response to a subset of the whole set available and provide links to traverse it. Pagination links will appear in the links object that correspond to a collection.

Some collections can be sorted using the sort query parameter. We support multiple sort fields by allowing comma-separated sort fields. The sort order for each sort field will be in ascending order unless it is prefixed with a minus.

For example:

GET /v2/teams/1/experiences?sort=status,-id  HTTP/1.1
Accept: application/vnd.api+json

Our API supports versioning so that, as we make breaking changes, it does not break your application. To specify a version, simply use the API-Version header. If you do not specify a version, your OAuth Application's version configuration will be used.

Available versions:

• 20190326 (current)

For example:

GET /v2/me HTTP/1.1
API-Version: 20190326

• We only accept bearer tokens via the Authorization header.
• Our WAF may block request that do not include a User-Agent header.
• POST, PUT and PATCH requests with a body must have the Content-Type header set to application/vnd.api+json as defined in the JSON:API specification unless specified otherwise.

A subaccount is an account that can be accessed directly using the specified account credentials such as an Instagram business or creator account or Facebook page.