Importing Users

Overview

The Zeta Marketing Platform offers flexibility in how users can be imported and synchronized. There are three primary methods available: Via JavaScript Library, API, and File Import. These methods can be used on their own or in tandem with one another based on the business requirements.

Via JavaScript Library

The Zeta Marketing Platform JavaScript library is called p13n.js. This library offers a client-side website integration with the platform using only a few lines of code. In order to manage users, p13n.js offers an updateUser method. Further documentation is available at our developer center.

Via API

While p13n.js offers a client side integration, the platform also offers a server-side integration with the REST API. There are a number of methods available including the ability to create or update a user and get a user. Further documentation is available at our developer center.

Via File Import

If batch user imports are a requirement, user files can be delivered to the platform FTP.

The platform accepts .jsonl (preferred) and .csv file formats.

  • Each file dropped into the FTP servers should be a UTF-8 encoded data file in one of the following formats:

    • JSONLines file with extension .jsonl (preferred)

    • Comma-Separated Values file with extension .csv

  • Each line in the file should represent a single user to be updated in your account.

Files should be dropped into the users folder in the FTP location for your account. The domain for all accounts is sftp.boomtrain.net and access credentials can be found in Settings → Integrations

JSONL

JSON Lines format enables more complex data structures to be represented for updating users.

JSON Line Files should be formatted as UTF-8 encoded text files with a.jsonl extension that consist of newline-delimited JSON objects. Each line in the file is an object representing the user to update. Any other fields to be added should be indicated as either attributes to update, or a list of contacts to add or update.

Sample JSONL File

Sample JSONL File
{"user_id": "user123", "status": "new_user","pets": [{"pet_type": "Dog","name": "Suki"},{"pet_type": "Rock","name": "Rocky"}], "interests": ["Shiba Inus", "Baseball", "User Experience Design", "Data Structures"],"contacts": [{"contact_type": "phone","contact_value": "559-867-5309"}]}
{"user_id": "user456","status": "new_user","pets": [{"pet_type": "Rat","name": "Raddigin"},{"pet_type": "Hamster","name": "Hammy"}], "interests": ["Shiba Inus", "Cooking", "Wine"],"contacts": [{"contact_type": "email","contact_value": "user456@example.com"}]}

Updating Subscription status for a contact

To set subscription status for a given contact, include the {{subscription_status}} attribute within a {{contact}} object. For example:

To unsubscribe a given contact:

{"user_id": "123","contacts": [{"contact_type": "email","contact_value": "user@email.com", "subscription_status":"inactive"}]}

To re-subscribe that contact:

{"user_id": "123","contacts": [{"contact_type": "email","contact_value": "user@email.com", "subscription_status":"active"}]}

CSV

Note that only String type user attributes can be updated using CSV files. For this reason, we highly recommend using JSONL format for your imports.

  • Column headers (first line of file) are limited to a maximum of 256 characters

  • Column values (second through last line of file) are limited to a maximum of 1024 characters

  • All fields should be separated by a comma character ( , ).

  • The double-quote character " may be used to enclose fields.

Examples

The double-quote character " may be used to enclose fields. This means that this three-column file is acceptable:

user_id,value_1,value_2
"1234","foo","foo,bar"

In this case, {{value_2}} will resolve to the value foo,bar.

If a double-quote character is used inside of an enclosed field, it must be preceded by another double-quote character, per the RFC-4180 specification. Thus, this three-column file is acceptable:

user_id,value_1,value_2
"1234","foo","foo,"""bar"""

In this case, {{value_2}} will resolve to the value "bar" (with quotes).

Handling Identity in User File Imports

One field will be required in each line of your user import file, regardless of file format: either a user_id or an email string. These identifiers are used to determine which user will be updated. Depending on the input provided and the state of those users in your account before the file import, these identifiers will be handled differently:

If your import includes ↓

0 user records match provided identifiers

Only email matches a user record

Only user_id matches a user record

Both email and user_id match the same user record

email and user_id each match different user records

email

A new user will be created with the provided value as their email identifier. This will be visible as the uid for the user in your ZetaHub account, and that email will automatically be added as an active contact for this user. All attributes and additional contacts provided will be added to this new user.

All attributes and contacts provided will be updated for the user who matched the email identifier.

N/A

N/A

N/A

user_id

A new user will be created with the provided value as their user_id identifier. This will be visible as the uid for the user in your ZetaHub account, and that email will automatically be added as an active contact for this user. All attributes and additional contacts provided will be added to this new user.

N/A

All attributes and contacts provided will be updated for the user who matched the user_id identifier.

N/A

N/A

email AND user_id

A new user will be created with the provided user_id value as their user_id identifier (which will be used as the uid for the user in your ZetaHub Account), and with the provided email value as their email identifier. That email will automatically be added as an active contact for this user. All attributes and additional contacts provided will be added to this new user.

All attributes and contacts provided will be updated for the user who matched the email identifier.


If this user does not already have a user_id identifier, the provided user_id value will be added as the user_id identifier for that user (and it will become the primary uid key for the user in your ZetaHub account).

If this user already has a different user_id identifier, the provided user_id will be ignored.

All attributes and contacts provided will be updated for the user who matched the user_id identifier.


If this user does not already have an email identifier, the provided email value will be added as the email identifier for that user, and that email will be added as an active contact for this user.

If this user already has a different email identifier, the provided email will be added as an additional contact to that user, and the email identifier for the user will be overwritten with the new value.

All attributes and contacts provided will be updated for the user matched.

All attributes and contacts provided will be updated for the user who matched the user_id identifier.


The email provided will be added as an active contact to this user.

Merging Users:

If the user who matched on email does not have a user_id and the user who matched on user_id does not have an email identifier, the user who matched on email will be merged into the user matched on user_id. The resulting single record will have the provided email and user_id identifiers.

See Progress of Your File Import

Within a couple of minutes, you’ll see your file begin to be processed in the following areas of the platform:

Feed Module

On the Dashboard page (https://app.zetaglobal.net/dashboard), a feed item will appear which shows the status of the upload. This will update with progress in real time and indicate the result of the file processing once complete.

File History Page

A full listing of previous file drops can be found in the File Import History page, found in Settings, or at https://app.zetaglobal.net/settings/file_imports. On this page, you’ll find a log of all event and user imports with their status. This page will update in real-time without the need to refresh for updates.

In the event that a file was unable to process due to one or more errors, those errors will be delivered here as a feedback file that can be accessed once the file has completely finished being processed. Simply click on the error icon to download the error file.