Customer API Overview

What is the Extole Customer API?

Extole's Customer API employs REST-style endpoints, which use an access token specific to a user to make all API calls. The REST API is designed to operate publicly on the internet between an end-user's browser and Extole—not behind a login or secure server-to-server connection—and there is no login call.

Customer API requests use the standard GET, PUT, POST, DELETE methods. All PUT/POST requests should include the header for Content-Type: application/json and Accepts: application/json.

How to Call the Customer API

Whenever you call the Extole Customer API, you must update the URL with your program domain.

For example, the URL for the Create Token endpoint is https://client.extole.io/api/v5/token. To successfully call this endpoint, replace client with your program domain. In other words, if Test Company were to call this endpoint, they would use the URL https://testcompany.extole.io/api/v5/token.

You can find your program domain in the Tech Center of the My Extole .

🚧

Important Note

Extole's JavaScript Library (core.js) is the most common way to create and utilize web experiences. Most of our clients never need to use the Customer API.

Access Tokens

Access tokens are the primary method for identifying the user calling into the Customer API.

There are three main methods for passing access tokens:

1. As a URL REST Parameter with he access token is passed as a URL parameter named access_token
2. In an Authorization header as Bearer TOKEN
3. In a cookie named access_token

Anytime the user makes a request, an access token is created and stored in a cookie. The token is a randomly generated number tied to a device profile (e.g., browser or mobile device). The initially granted access token is anonymous, meaning it is not tied to a program profile that contains PII.

Access tokens have three levels of security:

1. Anonymous: This is a device token that creates a journey history of activity, but is not tied to an identified profile.
2. Identified: A token becomes identified when either an email address or partner user id is passed through an API request. This allows the device token to get connected back to a identity profile inside the referral program. Identified tokens may add journey information into the identity profile, but they may not change information and they do not have access to any private profile data (name, friend information, reward information).
3. Verified: A token may be verified through email verification or a backend server-to-server verification. A verified token is granted full access to the profile, including the ability to make updates to profile properties.

Polling Pattern

The Customer API will return all API requests in less than 100ms (typically faster). There is never a blocking operation at Extole. Any request with logic that may take longer than 100ms will instead return a polling ID, and there will be a related method to poll with the identifier to wait for the operation to complete.

Debugging

Extole allows the header X-Extole-Debug to set debug levels of the Extole calls between one and three.