User Management API v1

Content

Introduction
Reference

Introduction

Authentication

ActivatePro uses header authentication. To obtain your API key, log in to the app and select System setup from the Settings dropdown. Copy the Master API value from the API keys section of the System setup page.

Versions

The API version is defined in the header X-XNG-ApiVersion. This documentation displays endpoints for version 1.

Headers

To use the ActivatePro API, define the following header values for each call made: X-XNG-AuthToken, X-XNG-ApiVersion.

Date Format

Dates and times are expressed in ISO8601 format in UTC (Coordinated Universal Time), with a special UTC designator ("Z") For more information please check here.

Error Handling

Resume or retry uploads that fail due to connection interruptions or 5xx errors such as the following:

500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

How to retry ActivatePro API requests in case of errors:

Use an exponential backoff strategy if an export request returns a 5xx server error. These errors can occur if a server is overloaded. Exponential backoff can alleviate such problems during periods of high request volume or heavy network traffic.

For other kinds of requests, do not use exponential backoff. Instead, retry a limited number of the desired requests.

Reference

User Attribute Management

Create Attribute

URL:

POST https://api.crossengage.io/users/attributes

Attributes
name required	The name of the user attribute traits.example	String
attributeType required	The type of the user attribute STRING, INTEGER, FLOAT, DATETIME, BOOLEAN or ARRAY	String
nestedType	The type of the nested attribute that will be added. Only applicable for array or object type. STRING, INTEGER, FLOAT, BOOLEAN, DATETIME, ARRAY or OBJECT	String

Request

Create a primitive attribute

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "name": "traits.example",
  "attributeType": "STRING"
}

Response

String attribute successfully created

200

Headers

ontent-Type:application/json;charset=UTF-8/code

Body

{
  "id": "111",
  "name": "traits.example",
  "attributeType": "STRING",
  "success": true
}

Request

Create an array attribute

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "name": "traits.exampleParent",
  "attributeType": "ARRAY",
  "nestedType": "STRING"
}

Response

Array attribute successfully created

200

Headers

ontent-Type:application/json;charset=UTF-8/code

Body

{
  "id": 305,
  "name": "traits.exampleParent",
  "attributeType": "ARRAY",
  "nestedType": "STRING",
  "success": true
}

Request

Create a nested attribute

Attributes
name required	The name of the user attribute traits.example	String
attributeType required	The type of the child attribute STRING	String
parentName required	string The name of the parent attribute traits.exampleParent	String

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "name": "exampleChild",
  "attributeType": "STRING",
  "parentName": "traits.exampleParent"
}

Response

Successful creation of attribute

200

Headers

Content-Type:application/json;charset=UTF-8/code

Body

{
  "id": "111",
  "name": "traits.example",
  "attributeType": "ARRAY",
  "success": true
}

Response

Attribute was not processed due to a validation error (see response)

400

Headers

Content-Type:application/json;charset=UTF-8/code

Body

{
  "requestId": "c2a20133-ecdd-4e43-8abd-943e5911737e",
  "message": "No enum constant com.crossengage.attribute.AttributeType.ARRAaY"
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

User attributes are called traits in ActivatePro. Please create all user attributes with the traits prefix, for example, traits.firstName. Please note that attributes cannot be created with the following protected suffixes: "_date", "_float", "_bool", "_string", "_nested", "_int".

When having to create a new attribute, please check the attribute list via the Fetch Attribute List endpoint to verify whether a similar or same attribute is available.

Fetch Attributes List

URL:

GET https://api.crossengage.io/users/attributes?offset=0&limit=2

Parameters
offset	The number of the first element. Example: `0`.	Number
limit	Number of elements to be returned. Default value is 10, maximum is 100. Example: `2`.	Number

Request

Headers

X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "attributes": [
    {
      "id": 1001,
      "name": "traits.example",
      "attributeType": "STRING"
    },
    {
      "id": 1002,
      "name": "traits.example2",
      "attributeType": "ARRAY"
    }
  ],
  "total": "200"
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

This endpoint fetches all existing user attributes.

Attribute management

This endpoint lets you fetch or delete an attribute according to its id.

Fetch Attribute

URL:

GET https://api.crossengage.io/users/attributes/id

Parameters
id	id of the attribute Example: 123.	String

Request

Headers

X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "id": "1234",
  "name": "traits.example",
  "attributeType": "STRING"
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

Fetch a specific user attribute by its id. To find an attribute id, please use the Fetch attribute list call.

Delete Attribute

URL:

DELETE https://api.crossengage.io/users/attributes/id

Parameters
id	id of the attribute Example: 123.	String

Request

Headers

X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

Attribute successfully deleted

204

Response

Wrong or missing credentials

401

Response

Attribute in use in at least one campaign or has active nested attributes. Otherwise, the id entered in the request body does not match the id provided in the request path.

409

Body

[
  {
    "id": 1234,
    "name": "traits.example",
    "usageType": "GOAL_CONDITION"
  }
]

Response

Unknown error on our side

500

In order to delete an attributes in ActivatePro, you need to know its id. To find it out, please use Fetch attribute list endpoint and search its id value.Note that deleting an attribute does not result in the removal of that attribute value from individual users. To modify individual users, it is necessary to update their profiles.

Lead management

Leads are users that don't possess customer ID also known as id in ActivatePro. Usually, these are prospects and newsletter subscribers who have an email address attached to their profile that serves as a primary identifier.

To promote a lead to a customer, all you need to do is to create a user with the same email address (or email and business unit). ActivatePro automatically merges the profiles when there is a match.

Create and Update a Lead

URL:

POST https://api.crossengage.io/leads/

Request

Attributes
email required	The lead's email john.doe@crossengage.io	String
businessUnit	The business unit of the lead DE	String
firstName	The lead's first name John	String
lastName	The lead's last name Doe	String
createdAt	The date the user was created in your database 2015-10-02T08:23:53Z	Datetime

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "updated": [
    {
      "id": "1234",
      "email": "john.doe@crossengage.io",
      "businessUnit": "US",
      "firstName": "John",
      "lastName": "Doe",
      "age": 21,
      "gender": "male"
    }
  ]
}

Response

The lead was processed successfully

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "updated": [
    {
      "id": "1234",
      "xngId": "1234",
      "success": true
    }
  ],
  "deleted": []
}

Response

Lead was not processed due to a validation error (see response)

400

Headers

Content-Type:application/json;charset=UTF-8

Body

  "updated": [
    {
      "xngId": "xng-id",
      "success": false,
      "errors": [
        {
          "field": "email",
          "type": "WRONG_FORMAT"
        }
      ]
    }
  ],
  "deleted": []
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

This endpoint lets you create or update leads. The system searches for existing leads based on records with email addresses and optionally business units. In case a record with the requested identifiers exists, the lead is updated. Otherwise, a new lead will be created.

User profile management

Individual user management

In ActivatePro, users are created and updated using the same method. The primary key used in both scenarios is id which is usually a customer ID in your database. Should it not be available for certain users, please consider creating them as leads instead - see Introduction to Leads Calls.

Create and Update a User

URL:

PUT https://api.crossengage.io/users/id

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Attributes
id required	The id of the user in your database 78ad0e3e-19e6-4ec1-84a7-b2c860c05387	String
email	The lead's email john.doe@crossengage.io	String
businessUnit	The business unit of the lead DE	String
firstName	The lead's first name John	String
lastName	The lead's last name Doe	String
createdAt	The date the user was created in your database 2015-10-02T08:23:53Z	Datetime

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "email": "john.doe@crossengage.io",
  "firstName": "John",
  "lastName": "Doe",
  "birthday": "1982-08-30",
  "createdAt": "2015-10-02T08:23:53Z",
  "gender": "male",
  "businessUnit": "DE"
}

Response

User has been created or updated successfully

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "id": "1234",
  "xngId": "asdgaw223-sf122-48211-1231-3155dff2",
  "email": "john.doe@crossengage.io",
  "businessUnit": "DE",
  "success": true
}

Response

User was not processed due to a validation error (see response)

400

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
  "xngId": "asdgaw223-sf122-48211-1231-3155dff2",
  "email": "john.doe+crossengage.io",
  "businessUnit": "unit",
  "success": false,
  "errors": [
    {
      "field": "email",
      "type": "WRONG_VALUE"
    }
  ]
}

Response

Wrong or missing credentials

401

Response

id sent in the request body does not match the id paramater entered in the request path

409

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
  "xngId": null,
  "email": "----------",
  "businessUnit": "DE",
  "success": false,
  "errors": [
    {
      "field": "id",
      "type": "user_IDS_MISMATCH"
    }
  ]
}

Response

Unknown error on our side

500

This endpoint lets you create or update a specific user by id.

Fetch a User

URL:

GET https://api.crossengage.io/users/id

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json

Body

{
  "email": "john.doe@crossengage.io",
  "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
  "xngId": "123e4567-e89b-12d3-a456-426655440000",
  "firstName": "John",
  "lastName": "Doe",
  "birthday": "1982-08-30",
  "createdAt": "2015-10-02T08:23:53Z",
  "gender": "male"
}

This endpoint lets you fetch a specific user by id.

Delete a User

URL:

DELETE https://api.crossengage.io/users/id

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

204

This endpoint lets you delete a specific user by id.

Bulk user management

This endpoint allows you to perform a number of operations with multiple users by sending a single call. The best application of bulk operations is creating, updating and/or deleting users at the same time.

Create & update or delete users in bulk

URL:

POST https://api.crossengage.io/users/batch

Request

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Attributes
id required	The id of the user in your database 78ad0e3e-19e6-4ec1-84a7-b2c860c05387	String
email	The lead's email john.doe@crossengage.io	String
businessUnit	The business unit of the lead DE	String
firstName	The lead's first name John	String
lastName	The lead's last name Doe	String
createdAt	The date the user was created in your database 2015-10-02T08:23:53Z	Datetime

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "updated": [
    {
      "email": "john.doe@crossengage.io",
      "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
      "firstName": "John",
      "lastName": "Doe",
      "birthday": "1982-08-30",
      "createdAt": "2015-10-02T08:23:53Z",
      "gender": "male"
    }
  ],
  "deleted": [
    {
      "email": "janice.doe@crossengage.io",
      "id": "62968d37-91f5-46f3-bd62-2432510f1a23",
      "firstName": "Janice",
      "lastName": "Doe",
      "birthday": "1987-06-15",
      "createdAt": "2015-10-02T08:23:53Z",
      "gender": "female"
    }
  ]
}

Response

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "updated": [
    {
      "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
      "xngId": "088818b3-445e-41a6-a7e1-cf86c8cdfbe4",
      "success": true
    }
  ],
  "deleted": [
    {
      "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
      "xngId": "ae86796f-8aca-4f65-a5dc-dea9a269f2a5",
      "success": true
    }
  ]
}

Response

400

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "updated": [
    {
      "id": "fb85fe50-a528-11e7-abc4-cec278b6b50a",
      "xngId": "088818b3-445e-41a6-a7e1-cf86c8cdfbe4",
      "success": false,
      "errors": [
        {
          "field": "id",
          "type": "NOT_NULL"
        },
        {
          "field": "email",
          "type": "WRONG_FORMAT"
        }
      ]
    }
  ],
  "deleted": [
    {
      "id": "78ad0e3e-19e6-4ec1-84a7-b2c860c05387",
      "xngId": "ae86796f-8aca-4f65-a5dc-dea9a269f2a5",
      "success": false,
      "errors": [
        {
          "field": "id",
          "type": "NOT_NULL"
        },
        {
          "field": "email",
          "type": "WRONG_FORMAT"
        }
      ]
    }
  ]
}

The maximum number of users that can be reached as per one call is 1000. Should you need to change more user profiles, please consider dividing them in successive calls.

Event management

Sending events

Event sending via API serves the following purposes:

Marketing automation for either transactional or commercial communication
User segmentation based on behavioural data
Collection of analytical insights for the improvement of pricing, UX or any specific business purpose

Send an Event

URL:

POST https://api.crossengage.io/events

Request

Attributes
id required	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.
email	Required if `id` is not available john.doe@crossengage.io
events required	object (array of objects)
event	Name of the event class in "events". Example: "event": "Viewed Page"
properties	List of event properties within "event". Example: "event": "Viewed Page", "properties":{ "cart":{}, "stringExample":"EU Landing Page", "integerExample":"150", "floatExample":"14.99", "arrayExample":"[] } Properties can be STRING, INTEGER, FLOAT, DATETIME, BOOLEAN or ARRAY (of Strings or Objects)
cart	A special array-property for cart-products.

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "id": "78ad0e3e-19e6-4ec1-84a7-b2c860c05387",
  "events": [
    {
      "event": "Completed Order",
      "properties": {
        "cart": {
          "total": 0,
          "currency": "EUR",
          "products": [
            {
              "id": "507f1f77bcf86cd879439023",
              "sku": "61979589",
              "name": "Zegna Shirt",
              "price": 150,
              "quantity": 1,
              "category": "Shirts",
              "hasZipper": false
            },
            {
              "id": "507f1f77bcf86cd799439011",
              "sku": "51979501",
              "name": "Levi Jeans",
              "price": 100,
              "quantity": 1,
              "category": "Jeans",
              "hasZipper": true
            }
          ]
        }
      }
    }
  ]
}

Response

202

Headers

Content-Type:application/json;charset=UTF-8

Response

Wrong format of the request (see response)

400

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "field": "event",
  "type": "UNKNOWN_VALUE"
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

Events are individually assigned to users. You can send up to 50 events per request. However, sending one single event per request is the most common practice.

Please note that the management of custom event property is not yet possible via API. In order to create a custom properties, please contact your customer experience manager.

Opt-out management

Status Endpoint

We highly recommend usage of opt-out and blacklist mechanisms. They ensure that users who have opted out or that have been blacklisted are never contacted. If you do not use these mechanisms you operate at your own risk.

A recipient's status is the cumulative information about communication channels that a specific user accepts messages in.

Get a User's status

URL:

GET https://api.crossengage.io/users/id/recipient-status

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json

Body

{
  "blacklisted": false,
  "optOutAll": false,
  "optOutChannels": []
}

Response

Wrong or missing credentials

401

Response

Unknown error on our side

500

Check the overall status of a particular user.

Opt Out Endpoint

You can opt a user out from a specific channel or from all messaging. The list of possible parameter values for the channel type are: MAIL, BROWSER_NOTIFICATION, ONSITE_DISPLAY, EXIT_INTENT, PUSH_NOTIFICATION, DIRECT_MAIL and SMS.

Update a user's opt out status

URL:

PUT https://api.crossengage.io/users/id/optout-status?channelType=MAIL

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String
channelType	The specific channel you'd like to update Example: `MAIL`.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "optOut": true
}

Response

200

Headers

Content-Type:application/json

Body

{
  "optOut": true
}

Response

Wrong or missing credentials

401

Response

This user does not exist

404

Response

Unknown error on our side

500

Update a specific user's overall opt out status or for a specific channel.

Read a user's opt out status

URL:

GET https://api.crossengage.io/users/id/optout-status?channelType=MAIL

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String
channelType	The specific channel you'd like to update Example: `MAIL`.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json

Body

{
  "optOut": true
}

Response

Wrong or missing credentials

401

Response

This user does not exist

404

Response

Unknown error on our side

500

Read a specific user's overall opt out status or for a specific channel.

Blacklist Endpoint

This endpoint allows you to read and update a user's blacklist status.

Update a user's blacklist status

URL:

PUT https://api.crossengage.io/users/id/blacklist-status

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Body

{
  "blacklisted": true
}

Response

200

Headers

Content-Type:application/json

Body

{
  "blacklisted": true
}

Response

Wrong or missing credentials

401

Response

This user does not exist

404

Response

Unknown error on our side

500

Read a user's blacklist status

URL:

GET https://api.crossengage.io/users/id/blacklist-status

Parameters
id	The id of the user in your database. Example: fb85fe50-a528-11e7-abc4-cec278b6b50a.	String

Request

Headers

Content-Type:application/json
X-XNG-ApiVersion:1
X-XNG-AuthToken:Your API Key

Response

200

Headers

Content-Type:application/json;charset=UTF-8

Body

{
  "blacklisted": true
}

Response

Wrong or missing credentials

401

Response

This user does not exist

404

Response

Unknown error on our side

500

Articles in this section

Content

Introduction

Authentication

Versions

Headers

Date Format

Error Handling

How to retry ActivatePro API requests in case of errors:

Reference

User Attribute Management

Request

Request

Request

Request

Attribute management

Request

Request

Lead management

Request

User profile management

Individual user management

Request

Request

Request

Bulk user management

Request

Event management

Opt-out management

Status Endpoint

Opt Out Endpoint

Request

Request

Blacklist Endpoint

Request