Importing People

Every platform user has a role that controls their access and permission levels. While different roles allow different levels of access to your environments, applications, and projects, you can always manage how your users can interact within your platform. After all, how people feel when interacting with a system or platform, can make it or break it for you. Adding your preferred set of people to the platform might be the best decision to take, considering we’re already here to make it easy for you.

The Zeta Marketing Platform offers flexibility across how people can be imported and synchronized. You can have a look at the quick start guides towards the beginning of the knowledge base to learn the manual import of individual or bulk users within the user interface (UI) via a CSV document upload. ZMP additionally facilitates the import of people via JavaScript Library, real-time APIs, and file imports. These methods can be used on their own or in tandem with one another based on the business requirements. Let’s have a quick look at how easy importing people can be:

Via JavaScript Library

The Zeta Marketing Platform JavaScript library, called p13n.js, offers a client-side website integration with the platform using only a few lines of code. In order to manage users, p13n.js offers a updateUser method.

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 identify a user, create or update a user and get a user.

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.

List Creation via FTP

Refer to Segment & Lists.

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 be updated. Any other field to be added should be indicated as either attributes to update, or a list of contacts to add or update.

Sample JSONL File:

CODE

{"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:

CODE

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

To re-subscribe that contact:

CODE

{"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 the file) are limited to a maximum of 256 characters
Column values (second through the last line of the 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:

CODE

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, as per the RFC-4180 specification. Thus, this three-column file is acceptable:

CODE

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

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

User Profile Photo Details:

The profile avatar can be derived by following the below instructions:

Users can upload an attribute by name {{avatar_url}} to a given user profile to render images (or add as an explicit property using the interface).
Square images (aspect ratio 1:1) will render the best. Note that if {{avatar_url}} exists on a profile, the default behavior of lookup from gravatar is overridden.

TXT

ZMP supports TXT files on FTP imports only.

Column headers (first line of the file) are limited to a maximum of 256 characters
Column values (second through the last line of the file) are limited to a maximum of 1024 characters
All fields should be separated by a comma character (,) or a pipe character (|) or a tab.
The double-quote character " may be used to enclose fields.

Examples:

Tab-delimited files:

CODE

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

Pipe-delimited files:

CODE

user_id|value_1|value_2
"1234"|"foo"|"bar"

Handling Identity in User File Imports

For Known Users

Either of the fields user_id or email string will be required in each line of your user import file, regardless of the file format. These identifiers are used to determine which user will be updated.

user_id is always converted to a lowercase string prior to being imported and saved.

Depending on the input provided and the state of the 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 ZMP 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

user_id

A new user will be created with the provided value as their user_id identifier. This value is converted to all lowercase prior to being saved. This will be visible as the uid for the user in your ZMP account. If this value is an email, then it 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

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 ZMP 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 ZMP 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.

For Unknown Users

ZMP supports offline ingestion of unknown users that may or may not have customer-provided identifiers (user_id or email) on record. ZMP currently supports the ingestion of such records with the following external identifiers, when the column headers are named as:

zync_id - Zeta cookie Id generated as a result of site integration with ZMP
email_md5_id - An md5 hash of emails that are at times used as a pseudo identifier but not necessarily a core identifier.

These records must have at least one external identifier if one of the core identifiers (user_id or email) is not provided.

Examples:

CODE

zync_id,value_1,value_2
"1234","foo","foobar"

CODE

email_md5_id,value_1,value_2
"1234","foo","foobar"

Besides the importing specifics for known and unknown users, the external IDs can also be uploaded in addition to the core identifiers.

Example:

CODE

user_id,zync_id,email_md5_id,value_1,value_2
"1234","5678","9012",foo","foobar"

Core identifiers, when available, take the priority to identify any existing record during the insert/update process.

For parent and child instances that has data sharing enabled, the system does not allow to update the profiles of users from the child instance if they are present in the parent instance.

In such scenarios wherein the users are present in parent and child instances, we will need to update their profiles from the parent instance only.

Check 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, 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 Settings > File Import History. On this page, you’ll find a log of all events 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.