Base URL for API Endpoints
All API URLs listed in this documentation are related to https://api.crossengage.io.
Names of the endpoints reflect the involved parts of the API. For example, the one for user creation and user update is reachable at https://api.crossengage.io/users/.
In order to authorize your API connection, please define the following properties for the header with each call you make:
- Content Type
Below you can find how to configure each property in the header.
API connected is authentificated via the header X-XNG-AuthToken.
In order to get the token, please log into the app, choose Settings → Developer and copy the value from the field called Public API Key.
API calls with empty or incorrect values in header or those without header will result in the response status
Versions of different endpoints are defined in the header X-XNG-ApiVersion. The currently supported version is 1.
The API currently supports requests and responses in JSON format. The property value is application/json.
Dates and datetimes are provided in ISO8601 format. Please see https://en.wikipedia.org/wiki/ISO_8601 for more details.
CrossEngage API considers two types of IDs - an internal one (externalId) and external one (xngGlobalUserId). email and businessUnit are additional user identifiers used to perform actions with datasets and events.
- externalId (alternatively: id) - a unique identifier refering to the customer ID in your company's database. At the same time, this is a primary key within the data structure of CrossEngage. The ID is not supposed to change in the course of user's lifecycle.
- xngGlobalUserId (alternatively: xngId) - a unique identified for a customer in CrossEngage database. The value is a UUID, although it is a subject to changes in case user removes cookies in the browser or logs in using multiple devices and browsers.
- email - an email address of a user.
- businessUnit - an entity within the business structure of your company. The values of the given attribute are of string data type and may contain any value. They usually represent the countries the company is active in, although may stand for various departments or any other structural split. For example, in case the company operates several websites which are considered different brands, it would make sense to differentiate them into distinct business units. This attribute is optional and should not apply in case it is not defined initially.
The combination of businessUnit and email is unique in CrossEngage. A person with the same email address and different business units is treated as two independent users.
Error Validation Types
Below is the list of possible error messages and their meaning.
|WRONG_JSON||The provided payload is not a valid json, therefore the request cannot be processed||
Ensure the syntax of json is valid.
Please check W3Schools for assistance
|TOO_MANY_EVENTS||Event limit was exceeded. A maximum of 50 events is allowed to send for a single user per one request||Split user events in multiple calls|
|UNKNOWN_USER||User does not exist or not identified||Ensure you provide a valid externalId or email address for a user|
|UNKNOWN_VALUE||The sent event did not pass the validation. It does not match any existing value according to the predefined list of values||
Ensure you provided a valid value by checking the spelling of the event name.
In case the event is not a default one and has not been sent previously, please request to enable it first by creating a ticket
At least one of user identifiers does not belong to the same user. Example: Saving two different users with unique externalIds and identifcal email address
|Ensure you provided a valid externalId, email address or business unit. You can fetch user by externalId and examine their email address|
|IS_NULL||null value was provided in a mandatory field||Provide a value which is not null|
|IS_EMPTY||No value was provided in a mandatory field||Provide a value which is not null|
|UNKNOWN_FIELD||User cannot be created or updated with the selected attribute because the attribute does not exist||Create a new attribute (see Create Attribute)|
|WRONG_TYPE||You tried to create or update a customer with an attribute value that does not match the type of the declared of the attribute.||
Ensure you provide the values of the correct type for the given attribute.
You can fetch an attribute (see Fetch Attribute) and compare its attributeType with type of value you provided in user request payload.
If an attribute has the wrong type, delete it (see Delete Attribute) and create the one with the right type (see Create Attribute). Please note that you can delete an attribute only if it has no current usages in your user journeys, goals and segments.
Provided value has the wrong format. Example: invalid date format
Ensure you provide values in the correct format. Please compare your request payload value with values provided in examples
The value you are creating already exists
Select another value or remove an existing item before recreating it