User data feed
CrossEngage's user data feed feature allows you to load all of your user base or to make regular uploads to keep your user base up to date when not using our API.
Note the following stipulations regarding the information which must be included in User Data Feed uploads.
  1. 1.
    externalId - Users cannot be updated without an external ID. If the external ID is not provided, CrossEngage will return an error. In CrossEngage, the terms externalId and id are both used, which might cause confusion. In feeds and API, the term id refers to externalId.
  2. 2.
    email and businessUnit - CrossEngage expects a user’s email and business unit to be present in all uploads. When these traits are not included in a user update, they will be deleted.

Introduction

To use our user data feed functionality, you must upload two JSON files to the SFTP server you have defined in the System Setup area of your account:
Header File
Data File
The header file allows you to define the data fields structure so that we may validate each of the fields on upload to ensure that no mistakes are made.
The data file contains the users and the attributes you would like to upload such as id, birthday, gender, name, email etc.

Naming convention

The naming convention for these 2 files is the following:
1
user_feed_header_YYYYMMDDHHMMSS.json
2
user_feed_data_YYYMMDDHHMMSS.json
Copied!

Example:

1
user_feed_header_20180321110559.json
2
user_feed_data_20180321110559.json
Copied!
Please ensure that a pair of header and data files always have the same timestamp and that the timestamp (YYYMMDDHHMMSS) is provided in the UTC timezone. If the pair does not have the same timestamp, our system will not process them.

Header File

Please consult the attribute list endpoint first to verify what the different field types are. It is quite important to also check if you already have similar attributes to avoid duplicates.
Please check our limitation documentation for user management here
This header file contains an array of objects which describe the type of attributes that may be loaded through a user object in the data file. The structure of these objects is as follows:
Key
Description
column_name
Name of the user attribute loaded through the user data file. The column name should always be sent in camelCase format e.g. firstName
data_type
This describes the type of data that will be loaded in the respective attribute. See all possible values in the Supported data types section below.
is_nullable
This property allows you to describe whether or not a field can NULL. Our system will automatically validate this to ensure that users will be updated correctly. Please note that the id field is mandatory and cannot be NULL.
Example
1
{
2
"column_name":"id",
3
"data_type":"text",
4
"is_nullable":"NO"
5
}
Copied!

Supported data types

Should your data file include any array attributes, please make sure to create these via API before uploading the file to our system to prevent our system from rejecting your file. Please find the documentation on how to create attributes via API here.
Data type
Description
Example
text
strings of different lengths
Some characters
date
A date e.g. birthdate
2016-03-22
timestamp
timestamp
2016-04-01T18:02:42+01
boolean
logical
true
integer
an integer number
42
numeric
any number
18.5

Example header file

1
[
2
{
3
"column_name":"id",
4
"data_type":"text",
5
"is_nullable":"NO"
6
},
7
{
8
"column_name":"firstName",
9
"data_type":"text",
10
"is_nullable":"YES"
11
},
12
{
13
"column_name":"lastName",
14
"data_type":"text",
15
"is_nullable":"YES"
16
},
17
{
18
"column_name":"email",
19
"data_type":"text",
20
"is_nullable":"YES"
21
},
22
{
23
"column_name":"birthday",
24
"data_type":"date",
25
"is_nullable":"YES"
26
},
27
{
28
"column_name":"gender",
29
"data_type":"text",
30
"is_nullable":"YES"
31
}
32
]
Copied!

Data File

This data file contains an array of objects which contain the data of the users that should be loaded into CrossEngage. Each object defines the attributes of a single user.
As mentioned in the Header File section above, the only mandatory field is the id. The id refers to the user identifier you have assigned to a customer in your data warehouse. This is the same id you might be already sending through our Tracking SDK or User Management API.
Please note that if you drop more than one file at the same time before they are being processed, only the most recent file will be processed. The older one(s) will be ignored.

Example user object:

1
{
2
"id": "JD1534",
3
"gender": "male",
4
"firstName": "James",
5
"email": "[email protected]",
6
"birthday": "1931-02-08",
7
"lastName": "Dean",
8
"lastOperation": {
9
"operationDate": "2016-08-20",
10
"type": "PURCHASE"
11
},
12
"subscriptions": [
13
{
14
"subscriptionId": "BI934",
15
"subscriptionName": "BILD daily"
16
},
17
{
18
"subscriptionId": "FA772",
19
"subscriptionName": "FAZ weekly"
20
}
21
],
22
"tags": ["tag1", "tag2"]
23
}
Copied!

Example data file

1
[
2
{
3
"id": "JD1534",
4
"gender": "male",
5
"firstName": "James",
6
"email": "[email protected]",
7
"birthday": "1931-02-08",
8
"lastName": "Dean",
9
"lastOperation": {
10
"operationDate": "2016-08-20",
11
"type": "PURCHASE"
12
},
13
"subscriptions": [
14
{
15
"subscriptionId": "BI934",
16
"subscriptionName": "BILD daily"
17
},
18
{
19
"subscriptionId": "FA772",
20
"subscriptionName": "FAZ weekly"
21
}
22
],
23
"tags": ["tag1", "tag2"]
24
},
25
{
26
"id": "JD1332",
27
"gender": "female",
28
"firstName": "Marilyn",
29
"email": "[email protected]",
30
"birthday": "1926-01-06",
31
"lastName": "Monroe",
32
"subscriptions": [
33
{
34
"subscriptionId": "SZ337",
35
"subscriptionName": "SZ weekly"
36
}
37
]
38
}
39
]
Copied!

Deleting Traits via User Data Feed

In order to delete a trait for a user, upload a user feed data file with xng-delete-trait as the value of the trait that should be deleted for that user:
1
[
2
{
3
"id": "123786543",
4
"zipCode":"xng-delete-trait"
5
}
6
]
Copied!

Standard User Attributes

The following is a list of standard attributes, which are built into the CrossEngage platform:
Name
Type
Example
traits.address
STRING
304 S Test St, Apt 3B, Austin, TX, 48934
traits.address.city
STRING
Austin
traits.address.country
STRING
US
traits.address.line1
STRING
304 S Test St
traits.address.line2
STRING
Apt 3B
traits.address.state
STRING
TX
traits.address.zip
STRING
48934
traits.age
INTEGER
45
traits.birthday
DATETIME
1975-06-27
traits.businessUnit (note: case sensitive)
STRING
de
traits.city
STRING
Berlin
traits.country
STRING
DE
traits.description
STRING
-
traits.email
STRING
traits.externalId
STRING
29743c2f-219a-4e90-a72c-240d9a473ed9
traits.feedback
STRING
-
traits.firstName
STRING
Clara
traits.gender
STRING
female
traits.id
STRING
dee6365f9608653d314049583006e265