Learn All About ZMP Identifiers

When creating a people profile in ZMP, the following are keys (system-generated and client 1st party), that can be used to identify and join for subsequent updates and event tracking:

System-Generated Keys

The following two are system-generated IDs that will be present for every client, and will always be generated:

bsin

A unique identifier that the ZMP system creates per profile, per site-id.
Every single profile (known/anonymous) in ZMP gets a BSIN. BSIN are globally unique, but from a usage perspective, they are tied to a particular site-id. Meaning, for example, for API calls, a site ID needs to be passed in along with BSIN. 
Hanging off the BSIN are alternate identifiers: user_id and email, which are unique per site-id. This allows our ZMP clients to use either unique user_ids as an identifier OR email address as an identifier OR both at the same time.

zync_id

A unique ID generated by the Zync Container Tag and assigned to each person that is browsing the client’s site.
Zeta is able to use the Zync_id to match the Zeta Identity Graph. 
Although the Zync_id remains the same for one profile, it can change if they change the device, or in case they clear their browser cookies. In such cases, the reidentification process can help link the new Zync_id with the existing user.

ZMP Profile Keys

The following three are client 1st party identifiers that can be used to create/update profiles.

user_id	This a single identifier - typically a 'golden key'
email (identifier)	A profile can have only 1 email identifier and can have up to 10 email contacts within the contacts array. If email(identifier) is set, it will also be captured as an email contact. Email as the identifier is a common method to use for site integration when a person presents their email_address on the website as a 1st-party site identification event  When using the 'email' identifier field, it is important to note that the email address will also be stored in the profile contacts along with up to 9 other email addresses – although only 1 can be used as an email identifier. The use of 'unique_client_ids' expands the possibility of using one of many keys to create/update a user.
unique_client_id	A profile can set many unique_client_id values (default is 10, more can be added, as requested). A unique_client_id value can be used to create/update a record via API, initiate a file-based campaign by only matching on that value, or a profile can accept multiple key:value pair names for a unique_client_id. No two profiles may have the same unique_client_id name:value. If a profile is added with a unique_client_id that is the same as another profile, the profiles will merge.

unique_client_id

user_id + email when combined creates their own key (i.e., you cannot input a different user_id + email key, else it will be rejected). A profile will always require either a user_id and/or email (identifier) as the key. The secondary key of 'unique_client_id' will allow for many IDs to be set up in advance and used to join to / update a given record.

If a client requires the use of the secondary unique_client_ids, the following functional components will be defined:

allow_lookup: if this is set to 'true' then the unique_client_id will be searchable via API and in the ZMP UI
allow_create_user:
- if true - create a new user when the call contains only a unique client ID. This will create a Zeta-assigned GUID placeholder user_id for the record
- if false - if the call comes through with a unique client ID only, Zeta fails the call with an error
id_names: object of the whitelisted id names (examples: loyalty_id, pos_account_id, plcc_id)
max_ids_allowed: the max number of allowed IDs for an account (by default this is set to 10 – but it can be expanded as requested)
- This number is the SUM TOTAL of values allowed for a given profile. For example, if you configure 3 identifiers and a max_ids_allowed of 10, then you can only store ten values across all 3 identifiers, NOT 10 per identifier.

In API calls

When submitting API calls, one typically uses 'uid' within the subscriber portion of the payload. ZMP interprets this and applies it either as an email identifier (if it is recognizable as an email address) or as a user_id (non-email values).

If the identifier provided as uid matches an existing record in ZMP, the update will be applied to that record.
If the provided identifier does not exist, a new record will be created with either email or user_id, as appropriate.  When using unique_client_id in API calls (for user update/create or track an event), the 'unique_client_id' value must be used.

Example:

CODE

"subscriber":{ "unique_client_ids":[ 
{
    "name":"%id_name%",
    "value":"%id_value"
              }
              ]
}

In Files

All files of profile data imported to ZMP must include either a user_id or email field. When including the 'unique_client_id_' field, it will be ingested as an identifier.

IDs can be imported via ZMP UI uploads by prefixing the ID name with "unique_client_id_". For example, if you have an ID named subscriber_id you can import a value for a person with the column header: unique_client_id_subscriber_id.

Paths that can be used to create a record
Action	Update Method(s)	System Behavior
create	--------------------------	--------------------------
user_id	File-based import (.csv, jsonl) REST API Javascript (p13n) File-based campaign	New user will be created with user_id as the 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. Note: no contact value is captured at this time.
email (identifier)	File-based import (.csv, jsonl) REST API Javascript (p13n) File-based campaign	A new user will be created with the provided value as their email 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.
user_id + email	File-based import (.csv, jsonl) REST API Javascript (p13n) File-based campaign	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.
unique_client_id	File-based import (.csv, jsonl)	A file-based import must include 'user_id' along with the 'unique_client_id_'
unique_client_id	REST API Javascript (p13n) File-based campaign	If the setting is enabled to 'allow_create_user' via unique_client_id, the REST API or JS (p13n) integration will create a user with unique_client_id set and a GUID hashed value as the user_id If the 'allow_create_user' value is not set, it will reject the record Note: if using a uid and a unique_client_id the uid will be prioritized and the unique_client_id is ignored, only use the latter by itself, otherwise continue using uid

Paths that can be used to update a record
Action	Update Method(s)	System Behavior
update	--------------------------	--------------------------
user_id	File-based import (.csv, jsonl) REST API Javascript (p13n) File-based campaign	User_id or UID can be used and will update existing record
email (identifier)	File-based import (.csv, jsonl) REST API Javascript (p13n)	Email or UID can be used and will update existing record
email (identifier)	File-based campaign	User_id is required field for all file-based campaigns. Email address can be used with header of 'user_id', and will be stored within the email contact field and email (identifier) field upon send
user_id + email	File-based import (.csv, jsonl)	User_id + email when combined create a composite-key. Thus, if on file the user_id + email that is provided does not match existing user_id+email identifier, it will be rejected
user_id + email	REST API Javascript (p13n)	As user_id + email exist on profile although via REST API or JS: Scenario A: Update existing profile with user_id AND email when each resolves to a different profile and the opposing identifier does not exist In this scenario, each profile only has the 1 value (profile 1: user_id only, profile 2: email address only). If on the incoming request it contains user_id and email, the email profile will do an implicit merge to the user_id profile. IMPLICIT merge, meaning we will not log a profile_consolidation event and the bsin will not be added to merged_bsins Scenario B: Update existing profile with user_id AND email when each resolves to a different profile and profiles contain multiple identifiers In this scenario, profile 1: user_id + email address, although the incoming request has email associated to a different user. This will prioritize the user_id match profile, and the email only profile is ignored. Scenario C: Update existing profile with user_id AND email when one field is provided as a null string or null value In this scenario, on incoming update user_id is populated, email is empty/null. The profile using user_id is prioritized and the email remains on profile, i.e. we do not nullify the email value
unique_client_id	File-based import (.csv, jsonl)	A file-based import must include 'user_id' along with the 'unique_client_id_'
unique_client_id	REST API Javascript (p13n) File-based campaign	For an existing user, 'unique_client_id' can be used as a method to update user or to qualify them on a campaign to deploy. If using on a file-based campaign, the unique_client_id_ must be present in the header row.