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 |
|
zync_id |
|
ZMP Profile Keys
The following three are client 1st party identifiers that can be used to create/update profiles.
user_id |
|
email (identifier) |
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 |
|
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:
"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. |