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.

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:

user_feed_header_YYYYMMDDHHMMSS.json
user_feed_data_YYYMMDDHHMMSS.json

Example:

user_feed_header_20180321110559.json
user_feed_data_20180321110559.json

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

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

{
"column_name":"id",
"data_type":"text",
"is_nullable":"NO"
}

Supported data types

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

[
{
"column_name":"id",
"data_type":"text",
"is_nullable":"NO"
},
{
"column_name":"firstName",
"data_type":"text",
"is_nullable":"YES"
},
{
"column_name":"lastName",
"data_type":"text",
"is_nullable":"YES"
},
{
"column_name":"email",
"data_type":"text",
"is_nullable":"YES"
},
{
"column_name":"birthday",
"data_type":"date",
"is_nullable":"YES"
},
{
"column_name":"gender",
"data_type":"text",
"is_nullable":"YES"
}
]

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.

Example user object:

{
"id": "JD1534",
"gender": "male",
"firstName": "James",
"email": "james.dean@yahoo.com",
"birthday": "1931-02-08",
"lastName": "Dean",
"lastOperation": {
"operationDate": "2016-08-20",
"type": "PURCHASE"
},
"subscriptions": [
{
"subscriptionId": "BI934",
"subscriptionName": "BILD daily"
},
{
"subscriptionId": "FA772",
"subscriptionName": "FAZ weekly"
}
],
"tags": ["tag1", "tag2"]
}

Example data file

[
{
"id": "JD1534",
"gender": "male",
"firstName": "James",
"email": "james.dean@yahoo.com",
"birthday": "1931-02-08",
"lastName": "Dean",
"lastOperation": {
"operationDate": "2016-08-20",
"type": "PURCHASE"
},
"subscriptions": [
{
"subscriptionId": "BI934",
"subscriptionName": "BILD daily"
},
{
"subscriptionId": "FA772",
"subscriptionName": "FAZ weekly"
}
],
"tags": ["tag1", "tag2"]
},
{
"id": "JD1332",
"gender": "female",
"firstName": "Marilyn",
"email": "marilyn.monroe@gmail.com",
"birthday": "1926-01-06",
"lastName": "Monroe",
"subscriptions": [
{
"subscriptionId": "SZ337",
"subscriptionName": "SZ weekly"
}
]
}
]

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

clara.schmidt@gmail.com

traits.externalId

STRING

29743c2f-219a-4e90-a72c-240d9a473ed9

traits.feedback

STRING

-

traits.firstName

STRING

Clara

traits.gender

STRING

female

traits.id

STRING

dee6365f9608653d314049583006e265

traits.interested

STRING

-

traits.isIdentified

BOOLEAN

true

traits.lastName

STRING

Schmidt

traits.mobileIds

ARRAY

-

traits.name

STRING

Clara Schmidt

traits.phone

STRING

+4933333333333

traits.postcode

STRING

48934

traits.title

STRING

-