We are pleased to welcome you to Exponea reference guides!

You are in the right place, if you want to dig deep into Exponea API. Here you can find the prerequisites for setting up API, code examples, API examples and guides that will help you with integrations between Exponea and your company.

If you want to learn more about Exponea APP itself, you can find more information in our documentation.

Suggest Edits

API overview

 
API name
API route

/data/v2/projects/{projectToken}/customers

/data/v2/projects/{projectToken}/catalogs

Recommendations

/data/v2/projects/{projectToken}/analyses

/track/v2/projects/{projectToken}/

Suggest Edits

Response types

 
Status code
Description

200

The request is completed successfully.

200

The request is completed, but you receive no permission message in a response.

No permission message means that you aren´t allowed to retrieve requested data. You have to set this permissions to data in Exponea APP (Settings-> API settings -> Get/set permissions).

400

The request is not JSON or the command (or one of the commands in case of batch route) is invalid.

401

The request is unauthorized, or there are insufficient rights.
You should check your authorization header. Check that the authorization type is correct (Basic/Token).

403

Forbidden access: The access keys used for authentication have been revoked.

404

The requested entity not found in your project. The ID doesn't exist.

429

The request reached rate limit.

Suggest Edits

Access keys

 

You have to set up access keys if you want to use any of Exponea APIs. Authentication for Exponea APIs is provided by 2 types of access keys - Public key, Private key.

Public key

Public key is used for frontend access. This method is used by our SDKs. Public key is used mainly for tracking and can be found in tracking code. Public key is used in a Token authentication and Basic authentication.

Use this key when you are exposing code that is publicly available.

It isn't recommended to use public key for personal data manipulation.

Private key

Private key is used to create public/private key pair and generate Authorization header for every API request. In this manner you are using basic authentication, where public key is username and private key is password, such like public_key:private_key. It is preferred to use public/private key combination compared to only public key, when you are doing integration between Exponea and your systems. Private key is used in Basic authentication.

Private key - rotate/revoke programatically

You have an option to rotate and revoke your private keys via API instead of using interface in Exponea APP. See these APIs in Rotate private key and Revoke private key section.

It is advised to rotate the private key every 7 days using the Rotate private key API call.

The private key should be kept safe and never shared since it gives you access to retrieve personal data.

Suggest Edits

Setting up access keys

 

Setting up public key in Exponea APP

  1. Go to Project Settings > Access management > API
  2. In API groups section, create a Public group for your public key
  3. You should see a screen with all keys within the group (GROUP KEYS) and data API options that private key can be used with (GROUP PERMISSIONS)
  4. Authentication with the public key is described in Token authentication and Basic authentication.

If you need more public keys, you can generate new public keys with + Add key in GROUP KEYS subsection.

Setting up private key in Exponea APP

  1. Go to Project Settings > Access management > API
  2. In API groups section, create a Private group for your private key
  3. Exponea pre-generates a private key for you. Keep the private key safe.
  4. You should see a screen with all keys within the group (GROUP KEYS) and data API options that private key can be used with (GROUP PERMISSIONS)
  5. Authentication with the private key is described in Basic authentication

If you need more private keys, you can generate new private keys with + Add key in GROUP KEYS subsection

Private key modification via API

Create new private key
For this purpose use API for rotation of private keys

Revoke existing private key
For this purpose use API for revoking of private keys

Suggest Edits

Basic authentication

 

Basic authentication is supported by a combination of public/private keys. In every API request that requires basic authentication you have to include authorization header with Basic auth hash generated from public/private key pair. In general, public key stands for username and private key for password.

  1. Combine public key and private key, separated with colon, such as public_key:private_key
0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqr:abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01
  1. Encode the combined keys as base64 to generate the authentication hash
MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcjphYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAx
  1. Once the hash is generated you can use it in a request header in the following format:
    Authorization: Basic <generated hash>
Authorization: Basic MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcjphYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAx

Base64 encoded strings can be decoded. Do not send the credentials in clear text and keep the Basic auth hash in private just as you would the private keys.

Suggest Edits

Token authentication

 

The public key is used for token based authentication. The public key can be used either as part of URL (query) parameter or as part of authorization header.

Public key as query parameter
Append the public key to API URL in the format:
?access_token=<public token>

https://api.exponea.com/path/to/route?access_token=0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqr

Public key as authorization header
Create an authorization header with the token in the format:
Authorization: Token <public token>

Authorization: Token 0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqr

Download data with Public key

The token authentication cannot be used anymore for downloading data from Exponea. All routes in a Customer API support only Basic authentication.

Suggest Edits

Rotate private key

 
posthttps://api.exponea.com/data/v2/projects/projectToken/access-keys/rotate
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/rotate \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/rotate',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/rotate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/rotate");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/rotate"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "new_private_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Path Params

projectToken
string
required

ID of your project

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Rotate key requires Basic authentication with public/private key pair.

Rotation of private key

The private key will still work for the next 48 hours.

You cannot have more than two private keys for one public key, therefore rotating the newly private key while the old key is still working will result in revoking old private key right away.

Rotating the old key twice will result in error, since you cannot have three keys at the same time.

Suggest Edits

Revoke private key

 
posthttps://api.exponea.com/data/v2/projects/projectToken/access-keys/revoke
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/revoke \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/revoke',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/revoke");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/access-keys/revoke"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true
}

Path Params

projectToken
string
required

ID of your project

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Revoke key requires Basic authentication with public/private key pair.

Revocation of private key

To revoke key right away just post an empty JSON to the revoke key route. Please note, that revoking this key can result in losing the access.

Suggest Edits

Customer API Overview

 

Customer API is dedicated for customer data manipulation.

Authorization

In order to work with this API you need to set up Basic authentication or Token authentication

API name
Description
Authentication method

Customer attributes

Retrieve attributes for customer. (e.g. customers ids, segmentations, predictions, properties, aggregations, expressions).

basic or token

Customer consents

Retrieve valid consents and consent information for specific customer.

basic

Customer profile data

Retrieve all data stored for specific customer (all attributes and all events).

basic or token

Export customers

Export customers in desired format (csv, json). This method should be used if you want to export multiple customers at once.

basic

Export events

Export events for specific customer in desired format (csv, json).

basic

Suggest Edits

Customer attributes

Retrieve customers aggregations, consents, expressions, IDs, predictions, properties, recommendations and segmentations

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "382d4221-3441-44b7-a676-3eb5f515157f"
 },
 "attributes": [
  {
   "type": "property",
   "property": "first_name"
  },
  {
   "type": "property",
   "property": "last_name"
  },
  {
   "type": "segmentation",
   "id": "592ff585fb60094e02bfaf6a"
  },
  {
    "type": "id",
    "id": "cookie"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": "Marian"
  },
  {
   "success": true,
   "value": "Galik"
  },
  {
   "success": true,
   "value": "Payers"
  },
  { 
   "success": true,
   "value": "382d4221-3441-44b7-a676-3eb5f515157f"
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

You can use various values for attributes. See Request params description below

type
property
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer attributes require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...).

Object of strings

Yes

attributes

Array of attribute objects that specify properties to be retrieved.

See below for available attribute object types and JSON code examples.

Array of objects

Yes

Suggest Edits

Customer aggregates

Retrieve aggregates for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "aggregate",
   "id": "0123456789abcdef01234567"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": 123
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each aggregate attribute must have type and id properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer aggregates require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for aggregate attribute object parameters.

Array of objects

Yes

Aggregate attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For aggregates, type must be aggregate.

String

Yes

id

ID of aggregation that you want to retrieve.

String

Yes

Suggest Edits

Customer consents

Retrieve valid consents and consent information for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "382d4221-3441-44b7-a676-3eb5f515157f"
 },
 "attributes": [
  {
   "type": "consent",
   "category": "newsletter"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": "true" // true for valid consent, false for invalid consent
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each consent attribute must have type and category properties.

type
category
mode

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer consents require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of consent attribute objects that specify properties to retrieve. Each attribute must have type and category properties.

See below for consent attribute object parameters.

Array of objects

Yes

Consent attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For consents, type must be consent

String

Yes

category

Category of a consent. These can be found in Consents Management -> Categories -> CONSENTS in CONSENT CATEGORY column

String

Yes

mode

Mode specifies what information about the consent should be fetched.

Default value is valid.

Mode options:
message - Returns a value from message attribute for last consent event category
source - Returns a source for last consent event
timestamp - Returns a timestamp for last consent event as UNIX time
valid - Returns whether consent is valid or not (true/false)
until - Returns a value from valid_until attribute for last consent event

String

No

Suggest Edits

Customer expressions

Retrieve expressions for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "expression",
   "id": "0123456789abcdef01234567"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": 123
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each expression attribute must have type and id properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer expressions require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for expression attribute object parameters.

Array of objects

Yes

Expression attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For expressions, type must be expression.

String

Yes

id

ID of expression that you want to retrieve.

String

Yes

Suggest Edits

Customer IDs

Retrieve IDs for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "id",
   "id": "registered"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": "sample@sample.com"
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each customer ID attribute must have type and id properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer IDs require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for customer ID attribute object parameters.

Array of objects

Yes

Customer ID attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For customer's IDs, type must be id.

String

Yes

id

Name of the external ID that you want to retrieve.

String

Yes

Suggest Edits

Customer predictions

Retrieve predictions for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "prediction",
   "id": "0123456789abcdef01234567"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": 0.8
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each prediction attribute must have type and id properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer predictions require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for prediction attribute object parameters.

Array of objects

Yes

Prediction attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For predictions, type must be prediction.

String

Yes

id

ID of prediction that you want to retrieve.

String

Yes

Suggest Edits

Customer properties

Retrieve properties for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "property",
   "property": "first_name"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": "John"
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each customer property attribute must have type and property properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer properties require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for customer property attribute object parameters.

Array of objects

Yes

Customer property attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For customer's property, type must be property.

String

Yes

property

Name of the property that you want to retrieve.

String

Yes

Suggest Edits

Customer segmentations

Retrieve segmentations for specific customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 },
 "attributes": [
  {
   "type": "segmentation",
   "id": "0123456789abcdef01234567"
  }
 ]
}
{
 "success": true,
 "results": [
  {
   "success": true,
   "value": "Frequent Buyers"
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

Array of attribute objects. Each segmentation attribute must have type and id properties.

type
id

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer segmentations require Basic authentication with public/private key pair.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Project Settings -> API -> GROUP PERMISSIONS, and check relevant Get/Set methods for attributes.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

attributes

Array of attribute objects that specify properties to retrieve.

See below for segmentation attribute object parameters.

Array of objects

Yes

Segmentation attribute

Parameter
Description
Data Type
Required

type

Type of customer's attribute. For segmentations, type must be segmentation.

String

Yes

id

ID of segmentation that you want to retrieve.

String

Yes

Suggest Edits

Export one customer

Retrieve all data stored for specific customer (all attributes and all events)

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/export-one
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/export-one \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/export-one',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/export-one")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/export-one");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/export-one"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "12345678-1234-1234-1234-123456789abc"
 }
}
{
 "success": true,
 "ids": {
  "cookie": [
   "12345678-1234-1234-1234-123456789abc",
   "abcdefgh-abcd-abcd-abcd-abcdefghi123"
  ],
  "registered": [
   "email@exponea.com"
  ]
 },
 "properties": {
  "first_name": "John",
  "last_name": "Smith",
  "email": "email@exponea.com"
 },
 "events": [
  {
   "type": "session_start",
   "timestamp": 1234567,
   "properties": {
    "browser": "Chrome",
    "device": "Other",
    "location": "https://app.exponea.com/",
    "os": "Linux"
   }
  },
  {
   "type": "purchase",
   "timestamp": 1234568.9,
   "properties": {
    "price": 1234.5,
    "product_name": "iPad"
   }
  },
  {
   "type": "session_start",
   "timestamp": 1234569,
   "properties": {
    "browser": "Chrome",
    "device": "Other",
    "location": "https://app.exponea.com/",
    "os": "Linux"
   }
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Customer expressions require Basic authentication with public/private key pair.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...)

Object of strings

Yes

Suggest Edits

Export all customers

Export all customers, who exist in the project

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/export
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/customers/export \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/customers/export',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/customers/export")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/customers/export");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/customers/export"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "attributes": {
  "type": "some",
  "list": [
   {
    "type": "id",
    "id": "registered"
   },
   {
    "type": "property",
    "property": "first_name"
   },
   {
    "type": "property",
    "property": "last_name"
   }
  ]
 },
 "filter": {
  "type": "segment",
  "segmentation_id": "592ff585fb60094e02bfaf6a",
  "segment_index": 1
 },
 "execution_time": 123456,
 "timezone": "Europe/Bratislava",
 "format": "table_json"
}
{
    "fields": [
        {'type': 'id', 'id': 'registered'},
        {'type': 'property', 'property': 'first_name'},
        {'type': 'property', 'property': 'last_name'}
    ],
    "data": [
        ['marian.galik@exponea.com', 'Marian', 'Galik']
    ]
}

Path Params

projectToken
string
required

id of your project

Body Params

attributes
object
 
attributes.type
string
required
attributes.property
string

Customer's property. Required for customer properties.

attributes.id
string

ID of the attribute. Required for aggregates, expressions, customer IDs, predictions and segmentations.

filter
object
 
filter.type
string
filter.segmentation_id
string
filter.segment_index
integer
execution_time
int32

Timestamp

timezone
string
format
string
required

Headers

Authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

Customer expressions require Basic authentication with public/private key pair.

Request params description

Parameter
Description
Required

attributes

Attributes that should be exported. If not specified, all properties and identifiers

No

attributes.type

some = only specified attributes in reqest
properties_and_ids = all properties and identifiers (default)

No

attributes.list

Define attributes, that you want to export. Only available when type: some is used

No

filter

Filter customers who should be exported. If not specified, all customers will be exported.

No

filter.type

segment = customers from segment
all = all customers

No

filter.segmentation_id

ID of segmentation that should be applied for filtering customers

No

filter.segment_index

Index of segment from the segmentation. Only customers from this segment will be exported. Indexed from 0. Customers that don't match any of the segments belongs to segment_index -1

No

execution_time

The timestamp that should the customer filter and attributes be evaluated on. Default current time

No

timezone

Which timezone should the customer filter and attributes be evaluated on. Default UTC

No

format

Output format.

csv - CSV table with header explaining which column corresponds to which attribute, in case of some attributes, the order is the same as specified in the list array. In other cases the first are ids, then properties and last the rest of attributes

table_json - same as CSV, but presented in JSON form (different than native_json, since this is basically a table converted to JSON)

native_json - native JSON format, almost the same as table_json, but the column names are not collapsed to strings

Yes

Suggest Edits

Export events

Export events for selected customers

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/events
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/events \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/events',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/events");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/events"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "382d4221-3441-44b7-a676-3eb5f515157f"
 },
 "event_types": [
  "session_start",
  "payment"
 ],
 "order": "asc",
 "limit": 3,
 "skip": 100
}
{
 "success": true,
 "data": [
  {
   "type": "session_start",
   "timestamp": 1234567.89,
   "properties": {
    "browser": "Chrome",
    "device": "Other",
    "location": "https://app.exponea.com/",
    "os": "Linux"
   }
  },
  {
   "type": "purchase",
   "timestamp": 1234568.9,
   "properties": {
    "price": 1234.5,
    "product_name": "iPad"
   }
  },
  {
   "type": "session_start",
   "timestamp": 1234569,
   "properties": {
    "browser": "Chrome",
    "device": "Other",
    "location": "https://app.exponea.com/",
    "os": "Linux"
   }
  }
 ]
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

event_types
array of strings
required

Events that you want to export

order
string

Order of exported events by timestamp (asc/desc) Default: asc

limit
int32

Number of items to return. Returns all items if no limit.

skip
int32

Number of items to be skipped from the beginning. Default: 0

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Authentication

Exporting events require Basic authentication with public/private key pair.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...).

Object of strings

Yes

event_types

Name of events that you want to export.

Array of strings

Yes

order

Order by timestamp. asc for ascending order (oldest to newest), desc for descending order (newest to oldest). Default: asc.

String

No

limit

Number of items to return. If not specified in request all events are returned.

Number

No

skip

Number of items to skip over. Default: 0

Number

No

Suggest Edits

Anonymize one customer

This call will delete a customer's attributes that you marked as PII in your project. Read more about this feature here.

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/anonymize
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/anonymize \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/anonymize',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/anonymize")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/anonymize");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/12345678-1234-1234-1234-123456789abc/customers/anonymize"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "customer_ids": {
    "cookie": "382d4221-3441-44b7-a676-3eb5f515157f"
  }
}
{
  "success": true
}

Path Params

projectToken
string
required

ID of your project

Body Params

customer_ids
object
required

Customer's IDs. At least one ID is required.

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

Headers

Authorization
string
required

How to authenticate please see section Access keys

Content-type
string
required

Content-type must be application/json

 

Anonymizing customer properties

Please note that apart from customer IDs, the anonymize call only removes properties that have been marked as PII (personal identifiable information). You need to specify manually which properties are PII in the Data manager. See our guide here.

Authentication

Customer attributes require Basic authentication with public/private key pair.

Anonymize method

Removes all external identifiers and assigns a new cookie ID. Removes customer properties that are marked as personal identifiable information (PII) with the yellow lock icon in the Data manager.

Request params description

Parameter
Description
Data Type
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) or custom IDs (email, phone...).

Object of strings

Yes

Suggest Edits

Anonymize customers - bulk

Anonymize multiple customers at once. This will delete their attributes that you marked as PII in your project. Read more about this feature here. The limit is 1000 customers per one request.

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/customers/anonymize_bulk"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{"customers": [
  {"customer_ids": {"registered": "steven@exponea.com"}},
  {"customer_ids": {"registered": "nataly@exponea.com"}},
  {"internal_id": "57e99c7bfb60099395b94b6d"}
]}
{"success": true}

Path Params

projectToken
string
required

id of your project

Body Params

customers
array of mixed types
required

Every item has this structure: {"customer_ids": {"registered": "steven@exponea.com"}}

Headers

Authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Anonymizing customer properties

Please note that apart from customer IDs, the anonymize call only removes properties that have been marked as PII (personally identifiable information). You need to specify manually which properties are PII in the Data Manager. See our guide here.

Please note that the limit is 1000 customers per request.

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Anonymize method

Removes all external identifiers and assigns a new cookie id. Removes all personal customer properties.

Request params description

Parameter
Description
Required

customers

Array of customers

Yes

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) as also custom IDs (email, phone...)

Yes

internal_id

Specify your customer with Exponea internal ID. Internal ID can be found in an URL of a specific customer. Open a customer in Data manager -> Customers. The ID is a hash from last part of URL crm/customers/5af08100cbf10c4dd674fab1

No

Suggest Edits

Recommendations for customer

Get items recommended for customer

 
posthttps://api.exponea.com/data/v2/projects/projectToken/customers/attributes
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/customers/attributes \
  --header 'authorization: Basic/Token <basic auth token/public token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/customers/attributes',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic/Token <basic auth token/public token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/customers/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic/Token <basic auth token/public token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/customers/attributes");
xhr.setRequestHeader("authorization", "Basic/Token <basic auth token/public token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/customers/attributes"

headers = {
    'authorization': "Basic/Token <basic auth token/public token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "customer_ids": {
  "cookie": "382d4221-3441-44b7-a676-3eb5f515157f"
 },
 "attributes": [
  {
   "type": "recommendation",
   "id": "592ff585fb60094e02bfaf6a",
   "fillWithRandom": true,
   "size": 10,
   "catalogFilter": [
    {
      "property": "gender",
      "constraint": {
        "type": "string",
        "operator": "equals",
        "operands": [
          {
            "type": "constant",
            "value": "male"
          }
        ]
      }
    }],
   "catalogAttributesWhitelist": ["item_id","title","link","image_link"],
   "no_track": false,
   "items": {
    "123": 2,
    "234": 4
   }
  }
 ]
}
{
 "success": true,
 "results": [] //items id
}

Path Params

projectToken
string
required

id of your project

Body Params

customer_ids
object
required

ID of customer

 
customer_ids.cookie
string

Customer cookie ID

customer_ids.registered
string

Customer registered ID

attributes
array of objects
required

You can use various values for attributes. See Request params description below

type
id
fillWithRandom
size
items
catalogFilter
catalogAttributesWhitelist
no_track

Headers

Authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token
  2. Token authentication with public token

Find more information about authentication in Access keys section.

Attributes accessibility

If a response includes message with no permission information please note that only some attributes are accessible. To set up attribute permissions go to Exponea APP -> Settings -> API settings -> allow get/set methods for attributes

Request params description

Parameter
Description
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) as also custom IDs (email, phone...)

Yes

attributes

Required:
type - only one option: recommendation
id - ID of your recommendation model
fillWithRandom - If set to true, fills the recommendations with random items until size is reached. This is utilized when models cannot recommend enough items.

Optional:
size - Specifies the upper limit for the number of recommendations to return. Defaults to 10.
items - If present, the recommendations are related not only to a customer, but to products with IDs specified in this array. Item IDs from catalog used to train the recommendation model need to be used. Input product IDs in a dictionary as {[product_id]: [weight]}, where the value weight determines the preference strength for the given product (bigger number = higher preference).
For example:

{"123": 1, "234": 2, "345": 4}

no_track - do no track events for items recommended by this operation
catalogAttributesWhitelist - Returns only specified subset of attributes from catalog items. If empty or not set, returns everything.

For example:

["item_id", "title", "link", "image_link"]

catalogFilter - Adds additional constrains to catalog when retrieving recommended items

Data Types Operands
Common is set, is not set, has value, has no value
Strings equals, does not equal, in, not in, contains, does not contain
Numbers equal to, in between, less than, greater than
Boolean is true, is false
Dates more than, less than, matches range, matches current day, matches current month, matches current year
Lists any items, all items

For example:

[
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": "jacket"
                }
            ],
            "operator": "contains",
            "type": "string"
        },
        "property": "name"
    },
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": ""
                }
            ],
            "operator": "has value",
            "type": "string"
        },
        "property": "description"
    },
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": "SUPER BRAND"
                }
            ],
            "operator": "equals",
            "type": "string"
        },
        "property": "brand"
    },
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": "Women"
                }
            ],
            "operator": "equals",
            "type": "string"
        },
        "property": "gender"
    },
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": "20"
                },
                {
                    "type": "constant",
                    "value": "100"
                }
            ],
            "operator": "in between",
            "type": "number"
        },
        "property": "price"
    },
    {
        "constraint": {
            "operands": [
                {
                    "type": "constant",
                    "value": "1"
                },
                {
                    "type": "constant",
                    "value": "0"
                }
            ],
            "operator": "greater than",
            "type": "number"
        },
        "property": "stock_level"
    }
]

Yes

Suggest Edits

Analysis API Overview

 

Authorization

In order to work with analyses API you need to set up Basic authentication

Suggest Edits

Funnels

Retrieve funnels

 
posthttps://api.exponea.com/data/v2/projects/projectToken/analyses/funnel
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/analyses/funnel \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/analyses/funnel',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/analyses/funnel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/analyses/funnel");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/analyses/funnel"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "analysis_id": "57a04d10fb6009d98f643260",
 "timezone": "Europe/Bratislava",
 "format": "native_json"
}
{
 "success": true,
 "name": "Conversion funnel",
 "steps": [
  "First visit",
  "Registration",
  "First log in",
  "Purchase",
  "Payment"
 ],
 "total": {
  "counts": [
   48632,
   24120,
   20398,
   1256,
   1250
  ],
  "times": [
   -1,
   680,
   4502,
   45,
   540,
   300
  ],
  "metric": 1987562
 },
 "drill_down": {
  "type": "none",
  "series": []
 },
 "metric": {
  "step": 4,
  "property": "price"
 }
}

Path Params

projectToken
string
required

Body Params

analysis_id
string
required
timezone
string
format
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Response description

Attribute
Description

name

Name of analysis

steps

Array that consist of funnel’s step’s names

total

Basic serie of funnel data with following format

counts - array that contains number of customers that reached the given step. Indices of the array matches indices of steps array

times - array that contains average number of seconds that took customer to reach given step from previous step. In case that the duration is unknown the value is -1. E.g. first value is always -1 since there is no previous step.

metric (Optional) - in case that you have saved your funnel with summarized metric this field will contain the metric result.

drill_down

type - Type of used drill down. Possible values:
none :no drill down at all, customer – by customer property
step – by step of funnel

property (Optional) - Tells by which property was drill down performed

step (Optional) - Tells by which step index (indexed from 0) was drill down performed.

series - Array of series. The structure of serie is the same as in total serie. Additionally it contains drilled down value under key with name key.

Request params description

Parameter
Description
Required

analysis_id

Id of analysis you want to retrieve

Yes

execution_time

To which timestamp should the analysis be evaluated. Default current time

No

timezone

Which timezone should the customer filter and attributes be evaluated on. Default UTC

No

format

Output format.

csv - CSV table with header explaining which column corresponds to which attribute, in case of some attributes, the order is the same as specified in the list array. In other cases the first are ids, then properties and last the rest of attributes

table_json - same as CSV, but presented in JSON form (different than native_json, since this is basically a table converted to JSON)

native_json - native JSON format, almost the same as table_json, but the column names are not collapsed to strings

Yes

Suggest Edits

Reports

Retrieve reports

 
posthttps://api.exponea.com/data/v2/projects/projectToken/analyses/report
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/analyses/report \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/analyses/report',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/analyses/report")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/analyses/report");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/analyses/report"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "analysis_id": "57a04d10fb6009d98f643260",
 "timezone": "Europe/Bratislava",
 "format": "native_json"
}

{
    "success": true,
    "name": "Conversion funnel",
    "steps": ["First visit", "Registration", "First log in", "Purchase", "Payment"],
    "total": {
        "counts": [48632, 24120, 20398, 1256, 1250],
        "times": [-1, 680, 4502, 45, 540, 300],
        "metric": 1987562
    },
    "drill_down": {
        "type": "none",
        "series": []
    },
    "metric": {
        "step": 4,
        "property": "price"
    }
}

Path Params

projectToken
string
required

Body Params

analysis_id
string
required
timezone
string
format
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Response description

Attribute
Description

name

Name of analysis

valid

Report is invalid when there are too many values for columns or rows.

header

Array of column names

drill_down

Array of rows where row is a dictionary with key equal to column name and value equal to calculated value

Request params description

Parameter
Description
Required

analysis_id

Id of analysis you want to retrieve

Yes

execution_time

To which timestamp should the analysis be evaluated. Default current time

No

timezone

Which timezone should the customer filter and attributes be evaluated on. Default UTC

No

format

Output format.

csv - CSV table with header explaining which column corresponds to which attribute, in case of some attributes, the order is the same as specified in the list array. In other cases the first are ids, then properties and last the rest of attributes

table_json - same as CSV, but presented in JSON form (different than native_json, since this is basically a table converted to JSON)

native_json - native JSON format, almost the same as table_json, but the column names are not collapsed to strings

Yes

Suggest Edits

Retentions

Retrieve retentions

 
posthttps://api.exponea.com/data/v2/projects/projectToken/analyses/retention
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/analyses/retention \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/analyses/retention',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/analyses/retention")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/analyses/retention");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/analyses/retention"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "analysis_id": "57a04d10fb6009d98f643260",
 "timezone": "Europe/Bratislava",
 "format": "native_json"
}
{
    "success": true,
    "name": "Payment retention",
    "rows": [{
        "date": 1410220800,
        "initial_step": 0,
        "cells": [0, 0, 0, 0, 0, 0, 0, 0]
    }, {
        "date": 1410307200,
        "initial_step": 0,
        "cells": [0, 0, 0, 0, 0, 0, 0, 0]
    }]
}

Path Params

projectToken
string
required

Body Params

analysis_id
string
required
timezone
string
format
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Response description

Attribute
Description

name

Name of analysis

rows

Array of rows from retention chart. Each row has following structure:
date - unix timestamp of the day on which row begins
initial_step - number of customers that have made the initial step on time period
cells - array of number of customers that have returned on Nth period after date where N is index of array starting from 0.

header

Array of column names

drill_down

Array of rows where row is a dictionary with key equal to column name and value equal to calculated value

Request params description

Parameter
Description
Required

analysis_id

Id of analysis you want to retrieve

Yes

execution_time

To which timestamp should the analysis be evaluated. Default current time

No

timezone

Which timezone should the customer filter and attributes be evaluated on. Default UTC

No

format

Output format.

csv - CSV table with header explaining which column corresponds to which attribute, in case of some attributes, the order is the same as specified in the list array. In other cases the first are ids, then properties and last the rest of attributes

table_json - same as CSV, but presented in JSON form (different than native_json, since this is basically a table converted to JSON)

native_json - native JSON format, almost the same as table_json, but the column names are not collapsed to strings

Yes

Suggest Edits

Segmentation

Retrieve segmentations

 
posthttps://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/analyses/segmentation"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "analysis_id": "57a04d10fb6009d98f643260",
 "timezone": "Europe/Bratislava",
 "format": "native_json"
}
{
    "success": true,
    "name": "Types of customers",
    "segments": [{
        "name": "Payers",
        "count": 450,
        "profile": {
            "Customer count": 450
        }
    }, {
        "name": "Non payers",
        "count": 1560,
        "profile": {
            "Customer count": 1560
        }
    }]
}

Path Params

projectToken
string
required

Body Params

analysis_id
string
required
timezone
string
format
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Response description

Attribute
Description

name

Name of analysis

segments

Array of segments with following format:
name - name of segment
count - number of customers that belongs to segment
profile - Dictionary of profile metrics where key is name of metric and value is calculated value. It additionally contains key with name Customer count that is the same value as count

Request params description

Parameter
Description
Required

analysis_id

Id of analysis you want to retrieve

Yes

execution_time

To which timestamp should the analysis be evaluated. Default current time

No

timezone

Which timezone should the customer filter and attributes be evaluated on. Default UTC

No

format

Output format.

csv - CSV table with header explaining which column corresponds to which attribute, in case of some attributes, the order is the same as specified in the list array. In other cases the first are ids, then properties and last the rest of attributes

table_json - same as CSV, but presented in JSON form (different than native_json, since this is basically a table converted to JSON)

native_json - native JSON format, almost the same as table_json, but the column names are not collapsed to strings

Yes

Suggest Edits

Catalog API Overview

 

Catalog API offers you to manipulate with catalogs in Exponea.

Authorization

In order to work with catalog API you need to set up Basic authentication

Suggest Edits

Create catalog

Create new catalog

 
posthttps://api.exponea.com/data/v2/projects/projectToken/catalogs
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/catalogs");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    'name': 'My Catalog',  # required
    'fields': [  # max 260 fields
        {
            'name': 'MyStringField',  # required
            'searchable': True,  # defaults to False
            'type': 'string',  # defaults to 'string'
        }, {
            'name': 'MyLongTextField',
            'type': 'long text',
        }, {
            'name': 'MyNumberField',
            'type': 'number',
        }, {
            'name': 'MyBooleanField',
            'type': 'boolean',
        }, {
            'name': 'MyDateField',
            'type': 'date',
        }, {
            'name': 'MyDurationField',
            'type': 'duration',
        }, {
            'name': 'MyListField',
            'type': 'list',
        }, {
            'name': 'MyUrlField',
            'type': 'url',
        }, {
            'name': 'MyJsonField',
            'type': 'json',
        }
    ],
    'is_product_catalog': True,  # defaults to False
}
{
 "success": true,
 "id": "5769788f830434fede37a017"  // _id of newly created catalog
}

Path Params

projectToken
string
required

id of your project

Body Params

name
string
required

Name for new catalog

fields
array of objects
required

List of columns for new catalog

name
type

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Request params description

Parameter
Description
Required

name

Name for new catalog

Yes

fields

List of columns for new catalog

Yes

Suggest Edits

Get list of all catalogs

Get list of all catalogs

 
gethttps://api.exponea.com/data/v2/projects/projectToken/catalogs
curl --request GET \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.exponea.com/data/v2/projects/projectToken/catalogs");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated


{
    "success": true,
    "data": {
        "id": "5769788f830434fede37a015",
        "name": "Products"
    }
}

Path Params

projectToken
string
required

id of your project

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Suggest Edits

Get catalog name

Get name of existing catalog

 
gethttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId
curl --request GET \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated


{
    "success": true,
    "data": {
        "id": "5769788f830434fede37a015",
        "name": "Products"
    }
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Suggest Edits

Get catalog items

Retrieve items for specific catalog

 
gethttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items
curl --request GET \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "success": true,
 "skip": 0,
 "limit": 20,
 "total": 1000, //total number of items in catalog
 "matched": 2, //number of items that matched query
 "matched_limited": false,
 "data": [ //returned items
  {
   "item_id": "1", //this field is used for updating or deleting items
   "catalog_id": "5769788f830434fede37a015",
   "properties": {
    "name": "iPad",
    "manufacturer": "Apple",
    "price": 500
   }
  },
  {
   "item_id": "2",
   "catalog_id": "5769788f830434fede37a015",
   "properties": {
    "name": "iPhone",
    "manufacturer": "Apple",
    "price": 700
   }
  }
 ]
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

Query Params

query
string
field
string
count
string
skip
string
order
string

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Query params description

Parameter
Description
Required
Example

query

Query string to match catalog's item properties and item_id

No

?query=Apple

field

If specified query string will be matched only against the property specified by this field (optional, can be item_id too)
Note: Works only with indexed catalog columns.

No

?query=Apple&field=manufacturer

count

How many items should be returned. Default value 20

No

?count=50

skip

How many items should be skipped. Default value 0
Count + skip shouldn't be greater than 1001, otherwise status code 400 will be returned

No

?skip=100&count=10

order

By which column should be result sorted.
Use format column_name order,secondary_column_name order,... where order is voluntary and can be desc or asc.

No

?order=price%20desc,manufacturer%20asc

Suggest Edits

Get catalog item

Get existing item with its properties from the catalog

 
gethttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId
curl --request GET \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "data": {
        "item_id": "1",
        "catalog_id": "5769788f830434fede37a015",
        "properties": {
            "name": "iMac",
            "manufacturer": "Apple",
        }
    }
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

itemId
string
required

id of item

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Query params description

Parameter
Description
Required
Example

query

Query string to match catalog's item properties and item_id

No

?query=Apple

field

If specified query string will be matched only against the property specified by this field (optional, can be item_id too)
Note: Works only with indexed catalog columns.

No

?query=Apple&field=manufacturer

count

How many items should be returned. Default value 20

No

?count=50

skip

How many items should be skipped. Default value 0
Count + skip shouldn't be greater than 1001, otherwise status code 400 will be returned

No

?skip=100&count=10

order

By which column should be result sorted.
Use format column_name order,secondary_column_name order,... where order is voluntary and can be desc or asc.

No

?order=price%20desc,manufacturer%20asc

Suggest Edits

Update catalog name

Update name of existing catalog

 
puthttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId
curl --request PUT \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "name": "Products",
 "fields": [
    {"name": "column1"}//you can use also empty array
 ]
}
{
    "success": true
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

Body Params

name
string
required

New name of catalog

fields
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Request params description

Parameter
Description
Required

name

New name for existing catalog

Yes

fields

List of columns in a catalog

Yes

Suggest Edits

Catalog item

Create or update catalog item

 
puthttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId
curl --request PUT \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "properties": {
        "name": "iMac",
        "manufacturer": "Apple"
    }
}
{
    "success": true, 
    "queued": true //Returned queued flag in response tells that the operation wasn't executed immediately, but was scheduled for asynchronous execution
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

itemId
string
required

Body Params

properties
object
required
 
properties.name
string
properties.type
string

Data type (defaults to string)

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Request body

Key in any of properties cannot contain NUL, dot (.), dollar ($), or be empty

If you want to do update of item just with several properties, use Catalog item (partial-update) route. In case of Catalog item route only defined properties are updated. Other properties that aren´t specified in request become empty.

Request params description

Parameter
Description
Required

properties

Definition of properties in key/value format.

"properties": {
        "name": "iMac",
        "manufacturer": "Apple",
        "prop3": "prop3_value",
        .....
    }

Yes

Suggest Edits

Catalog item (partial-update)

Update catalog item with specified properties

 
posthttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update
curl --request POST \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId/partial-update"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "properties": {
        "name": "iPhone"
    }
}
{
    "success": true, 
    "queued": true //Returned queued flag in response tells that the operation wasn't executed immediately, but was scheduled for asynchronous execution
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

itemId
string
required

Body Params

properties
object
required
 
properties.name
string
properties.type
string

Data type (defaults to string)

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Request body

Key in any of properties cannot contain NUL, dot (.), dollar ($), or be empty

Catalog item (partial-update) route compared to Catalog item updates only specified properties of item. If a property of an item isn´t specified in request, this property keeps unchanged.

Request params description

Parameter
Description
Required

properties

Definition of properties in key/value format.

"properties": {
        "name": "iMac",
        "manufacturer": "Apple",
        "prop3": "prop3_value",
        .....
    }

Yes

Suggest Edits

Delete catalog

Delete existing catalog

 
deletehttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId
curl --request DELETE \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication inAccess keys section.

Suggest Edits

Delete catalog item

Delete existing item in catalog

 
deletehttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId
curl --request DELETE \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items/itemId"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "queued": true //Returned queued flag in response tells that the operation wasn't executed immediately, but was scheduled for asynchronous execution
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

itemId
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Suggest Edits

Delete catalog items

Delete all catalog items, but catalog will still exists

 
deletehttps://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items
curl --request DELETE \
  --url https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/data/v2/projects/projectToken/catalogs/catalogId/items"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "queued": true //Returned queued flag in response tells that the operation wasn't executed immediately, but was scheduled for asynchronous execution
}

Path Params

projectToken
string
required

id of your project

catalogId
string
required

id of existing catalog

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access keys section.

Suggest Edits

Tracking API Overview

 

Authorization

In order to work with analyses API you need to set up Token authentication

Suggest Edits

System time

Get current unix timestamp on our servers

 
gethttps://api.exponea.com/track/v2/projects/projectToken/system/time
curl --request GET \
  --url https://api.exponea.com/track/v2/projects/projectToken/system/time \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.exponea.com/track/v2/projects/projectToken/system/time',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/track/v2/projects/projectToken/system/time")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.exponea.com/track/v2/projects/projectToken/system/time");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/track/v2/projects/projectToken/system/time"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{"success": true, "time": 123456.78}

Path Params

projectToken
string
required

id of your project

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token
  2. Token authentication with public token

Find more information about authentication in Access keys section.

When to use?

Use when you want to generate timestamp of the event from your system to synchronize the clock between your time and our server time.

Suggest Edits

Update customer properties

Update customer properties

 
posthttps://api.exponea.com/track/v2/projects/projectToken/customers
curl --request POST \
  --url https://api.exponea.com/track/v2/projects/projectToken/customers \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/track/v2/projects/projectToken/customers',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/track/v2/projects/projectToken/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/track/v2/projects/projectToken/customers");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/track/v2/projects/projectToken/customers"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "customer_ids": {"registered": "marian@exponea.com"},
    "properties": {
        "first_name": "Marian",
        "email": "marian@exponea.com"
    }
}
{"success": true}

Path Params

projectToken
string
required

id of your project

Body Params

customer_ids
object
required
 
customer_ids.cookie
string
customer_ids.registered
string
properties
object
required
 
properties.first_name
string
required
properties.email
string

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token
  2. Token authentication with public token

Find more information about authentication in Access keys section.

Sending more data

It is strongly prohibited to use this route for sending large volume of data in a way (one customer per one request). You should use Batch commands method instead.

Request params description

Parameter
Description
Required

properties

Object with customer properties.

name_of_property: value_of property

Yes

Suggest Edits

Add event

Add events for specific customer

 
posthttps://api.exponea.com/track/v2/projects/projectToken/customers/events
curl --request POST \
  --url https://api.exponea.com/track/v2/projects/projectToken/customers/events \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/track/v2/projects/projectToken/customers/events',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/track/v2/projects/projectToken/customers/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/track/v2/projects/projectToken/customers/events");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/track/v2/projects/projectToken/customers/events"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "customer_ids": {"registered": "marian@exponea.com"},
    "event_type": "purchase",
    "timestamp": 123456.78, 
    "properties": {
        "price": 1234.50,
        "name": "iPad"
    }
}
{"success": true}

Path Params

projectToken
string
required

id of your project

Body Params

customer_ids
object
required
 
customer_ids.cookie
string
customer_ids.registered
string
properties
object
required
 
properties.price
string
properties.product_name
string
timestamp
string
event_type
string

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token
  2. Token authentication with public token

Find more information about authentication in the Access keys section.

Sending more data

It is strongly prohibited to use this route for sending large volume of data in a way (one customer per one request). You should use Batch commands * method instead.

Request params description

Parameter
Description
Required

customer_ids

Specify your customer with external ID.

You can use either default external IDs (cookie, registered) as also custom IDs (email, phone...)

Yes

properties

Object with event values.

event_attribute: value_of attribute

No

timestamp

Unix timestamp when the event was created. If not present the current time is used

No

event_type

Name of event

Yes

Suggest Edits

Batch commands

Use this route when you want to execute several commands from tracking API group at once

 
posthttps://api.exponea.com/track/v2/projects/projectToken/batch
curl --request POST \
  --url https://api.exponea.com/track/v2/projects/projectToken/batch \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/track/v2/projects/projectToken/batch',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/track/v2/projects/projectToken/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/track/v2/projects/projectToken/batch");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/track/v2/projects/projectToken/batch"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "commands": [
  {"name": "system/time"},
  {
   "name": "customers",
   "command_id": "abc",
   "data": {
    "customer_ids": {
     "registered": "marian@exponea.com"
    },
    "properties": {
     "first_name": "Marian",
     "last_name": "Galik"
    }
   }
  },
  {
   "name": "customers/events",
   "data": {
    "customer_ids": {"registered": "marian@exponea.com"},
    "event_type": "purchase",
    "timestamp": 123456.78,
    "properties": {
     "price": 1234.5,
     "name": "iPad"
    }
   }
  }
 ]
}
{
    "success": true,
    // List of results for the commands specified in the request. 
    //The length of this list is
    // always the same as the length of list specified above.
    "results": [
        {"success": true, "time": 123456},
        {"success": true, "command_id": "abc"},
        {"success": true}
    ],
    "start_time": 123456,  // unix timestamp when the request started execution
    "end_time" 123457  // unix timestamp when the request stopped execution
}

Path Params

projectToken
string
required

id of your project

Body Params

commands
string
required

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Authentication

In this API call you can use two types of authentication:

  1. Basic authentication with private token
  2. Token authentication with public token

Find more information about authentication in Access keys section.

Sending more data

Use this route to send more data at once. Maximum size of command request is 50 commands per request.

How to build a command body?

In general all routes mentioned in Tracking API section can be used as part of command. Maximum size. Maximum size of command request is 50 commands per request

Command body is built by appending request bodies from following routes:

  1. Add event
  2. Update customer properties
{
 "commands": [
  {"name": "system/time"},
  {
   "name": "customers",
   "command_id": "abc",
   "data": {
    "customer_ids": {
     "registered": "marian@exponea.com"
    },
    "properties": {
     "first_name": "Marian",
     "last_name": "Galik"
    }
   }
  },
  {
   "name": "customers/events",
   "data": {
    "customer_ids": {"registered": "marian@exponea.com"},
    "event_type": "purchase",
    "timestamp": 123456.78,
    "properties": {
     "price": 1234.5,
     "name": "iPad"
    }
   }
  }
 ]
}
{
	"name": "customers", // name is created as end of a route for particular method
	"command_id": "1234", // this ID is returned in reponse. You can use command_id to mark your commands and do retry if error occurs in response
	"data": {
		"customer_ids": {
			"registered": "marian@exponea.com"
		},
		"properties": {
			"first_name": "Marian",
			"last_name": "Galik"
		}
	}
}
{
	"name": "customers/events", // name is created as end of a route for particular method
	"data": {
		"customer_ids": {"registered": "marian@exponea.com"}, // You have to always specify one external customer ID in case of event command
		"event_type": "purchase",
		"timestamp": 123456.78,
		"properties": {
			"price": 1234.5,
			"name": "iPad"
		}
	}
}
{"name": "system/time"}

Request params description

Parameter
Description
Required

commands

The list of commands you want to include in request.

Take a look section above - How to build a command body

Suggest Edits

Transactional email

Trigger emails from API and send through Exponea (In release 1.137)

 
posthttps://api.exponea.com/email/v2/projects/projectToken/sync
curl --request POST \
  --url https://api.exponea.com/email/v2/projects/projectToken/sync \
  --header 'authorization: Basic <basic auth token>' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.exponea.com/email/v2/projects/projectToken/sync',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Basic <basic auth token>' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.exponea.com/email/v2/projects/projectToken/sync")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic <basic auth token>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.exponea.com/email/v2/projects/projectToken/sync");
xhr.setRequestHeader("authorization", "Basic <basic auth token>");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);
import requests

url = "https://api.exponea.com/email/v2/projects/projectToken/sync"

headers = {
    'authorization': "Basic <basic auth token>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
 "integration_id": "5b337eceeb7cdb000d4e20f3",
 "email_content": {
  "template_id": "5b3399dfeb7cdb000df64477",
  "html": "<!DOCTYPEhtml><body></body></html>",
  "subject": "SubjectExample",
  "sender_address": "sarah.tancredi@example.com",
  "sender_name": "Sarah", 
  "params": {
   "first_name": "Michael",
   "last_name": "Scofield"
  },
  "attachments": [{
   "filename": "example.txt",
   "content": "RXhhbXBsZSBhdHRhY2htZW50",
   "content_type": "text/plain"
  }]
 },
 "campaign_name": "MyCampaign",
 "recipient": { 
   "customer_ids": {
    "registered": "3232eroofs23fsdsd"
   }, //required
   "email": "jon.doe@example.com",
   "language": "nl"
  }
}
{"success": "True"}

Path Params

projectToken
string
required

id of your project

Body Params

integration_id
string

ID of integration for your ESP (Email service provider)

email_content
object
required
 
email_content.template_id
string
email_content.html
string
email_content.subject
string
required
email_content.sender_address
string
required
email_content.sender_name
string
required
email_content.params
string
email_content.attachments
json
campaign_name
string
required
recipient
object
 
recipient.email
string

ID and value of your customer as defined in Exponea

recipient.customer_ids
json
required
recipient.language
string

Language localization of your template

Headers

authorization
string
required

How to authenticate please see section Access tokens

Content-type
string
required
 

Contact us to use Email API

Email API is by default disabled. If you want to use it or test it, please contact your Customer Success Manager or our support. We will set up Email API for you based on your needs.

Authentication

In this API call you can use these types of authentication:

  1. Basic authentication with private token

Find more information about authentication in Access tokens section.

Request params description

Parameter
Description
Required

integration_id

Integration ID of your Email service provider. If you have set a default email provider in the project settings this field is not required - the default provider will be used

No

email_content.template_id

This field not required however when you use template_id, you don´t need to specify other fields such as:
html
subject

If you use template_id you cant use html

Yes/No

email_content.html

This field is required when template_id is not defined.

In html field define your HTML content between <html></html> tags. Also CSS is accepted.

If you use html you cant use template_id

Yes/No

email_content.subject

This field is required when template_id is not defined.

In this field you store content for subject of your email

Yes/No

email_content.sender_address

Email address of the sender

Yes

email_content.sender_name

This is usually a first name of sender

Yes

email_content.params

Parameters for Jinja template engine. We use Jinja template engine for content personalization of emails. You can provide all the required data for email personalization in params. It will spare us from making extra requests to our database and leverage reliability of the API.

Specify use of params in the template like this:
Hello {{params.first_name}}{{params.surname}}. Then in the request provide us with the values that should be used instead of params.first_name and params.surname.

This works only when using templates not raw html content.

No

email_content.attachments

This field specifies the attachment of your email.
filename: Name of attachment
content: Encoded content of your file (base64)
content_type: Format of your attachments

Max. attachment size in total: 1 MB. Max. number of attachments: 10.

No

campaign_name

Name of email campaign

Yes

recipient.customer_ids

Specify customers with customer_ids field. You can use either default external IDs (cookie, registered) or also custom IDs (phone, email...). See Administration -> Projects -> <your project> -> Identifiers.

Yes

recipient.email

email field stores email of your customer. If email field is not defined in a request, email is automatically provided from customer profile in Exponea

Yes/No

recipient.language

Language version of your template. If the template has several language versions created, you can choose which one to use for this email. See available language abbreviatons in your
Project Settings -> Languages.

No