---
title: "User Identifiers in Mapp Connect"
slug: "user-identifiers-in-mapp-connect"
updated: 2024-11-25T09:29:32Z
published: 2024-11-25T09:29:32Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Identifiers in Mapp Connect

## Overview

Mapp Connect supports various user identifiers to streamline user event processing across different integration types and subtypes. This setup enables greater flexibility in managing user data based on unique identifiers (e.g., email addresses) and non-unique identifiers (e.g., defined in your external systems or specified as a custom attribute).

## Supported Identifiers

Mapp Connect provides unique identifiers and a non-unique identifier for user events:

[2024-11 Connect Identifiers](https://player.vimeo.com/video/1032375874?badge=0&autopause=0&player_id=0&app_id=58479)

- **Unique Identifiers**:
  - `userID`: The Contact ID that every Mapp Engage contact gets assigned in the system upon creation.
  - `email`: The user’s address.
  - `mobileNumber`: The mobile phone number used as an identifier.
- **Non-Unique Identifiers** (available only for “User” subtype events):
  - `externalID`: An identifier generated within an external system. In Mapp Engage, it is often referred to as `user.identifier`.
  - Additionally, we provide the possibility to match users by leveraging custom attributes, which enables flexible targeting and user management. To see how it works, go to the section [Leveraging Custom Attributes to Match Users](/v1/docs/user-identifiers-in-mapp-connect#leveraging-custom-attributes-to-match-users).

## Unique Identifiers

Unique User identifiers are available for the following subtypes: `wishlist`, `abandonedCart`, `recommendedproduct`, `automation`, `webpush`, `push`, `transaction`, `email`, `sms`.

Pay attention to using the correct Subtype (location) while setting up the mapping. This subtype matches the event type name from the API call. The call won't be processed if there is no mapping for the event type. For example, you must define a mapping with the subtype Email to send an email. For details, see [Edit Mapping](/v1/docs/edit-mapping).

![](https://cdn.document360.io/554b9b98-6720-4d8b-9919-c7b203d72648/Images/Documentation/wishlist.PNG)

*Example: Mapping with the Location (subtype) “wishlist“*

## Non-Unique Identifiers

The non-unique identifier is only available for the “User” subtype.

![](https://cdn.document360.io/554b9b98-6720-4d8b-9919-c7b203d72648/Images/Documentation/user.PNG)

> If multiple contacts share the same value for a non-unique identifier, any user update event will apply to all contacts with that identifier value.

## Requirements and Processing Hierarchy

#### **Unique & Non-unique Identifiers**

Each user event must include at least one unique identifier to ensure proper processing. Mapp Connect processes user events using the following identifier hierarchy:

1. **userID**: The system first checks for a match using the `userID`.
2. **Email**: If no `userID` match is found, it searches by email.
3. **Mobile Number**: If no email match is found, it searches by `mobileNumber`.
4. **External ID**: If no `mobileNumber` match is found, it checks for the `externalID`.

#### **Handling Missing Identifiers**

If no matching identifier (e.g.,`userID`, `email`, or `mobileNumber`) is found, the system processes the events as follows:

1. **Transaction Events**: A new user profile is created.
2. **User Events**: A new user profile is created if the `update-only` import mode is either absent or explicitly set to `false` (the default behavior). If the `update-only` mode is set to `true`, no new user profile will be created.

```json
{
  "email": "user@mapp.com",
  "updateonly": "true"
}
```

In this case, the profile will not be created.
3. **Email Events:** If no matching identifier is found, the system sends an email to the specified address using only the data provided in the event. No additional user data is loaded, and personalization is limited to the information included in the event.
4. **All Other Event Types**: The event is skipped unless it falls under the categories above (`Transaction`, `User` or `Email`).

#### **Matching Users with a Custom Attribute**

Users can be matched using a specified custom attribute included in the JSON payload. When the attribute is specified and provided, the system will prioritize matching via the custom attribute. If the user cannot be matched with the provided custom attribute, unique identifiers will not be used as a fallback. Standard attributes are not supported for user matching.

**Matching Logic Example**

If an event includes both an email and mobile number, the system checks the email first. If no match is found, it then searches by mobile number. This approach ensures consistency and accuracy when identifying users across multiple data sources.

**Example 1: The user profile is updated**

- **Event 1**: The system receives an event with the email `user@mapp.com`.
  - **Result**: It creates a new user with `userId 1` and email `user@mapp.com`.
- **Event 2**: The system registers another event with the same email (`user@mapp.com`) and, additionally, a mobile number (`+1234152563`).
  - **Result**: The existing user (`userId 1`) is updated to include both the email `user@mapp.com` and the mobile number `+1234152563`.

**Example 2: A new user is created**

- **Event 3**: The system receives a new event with a different mobile number (`+987456321`) and no email or user ID.
  - **Result**: The system will create a new user with `userId 2` and mobile number (`+987456321`).
- **Event 4**: The system receives a new event with the same mobile number (`+987456321)` which belongs to `userId 2` and the same email `user@mapp.com` which belongs to `userId 1`.
  - **Result:** In this use case, the system will not merge the profiles.

> Please consider that Mapp Engage as a standard behavior does not support the merging of user profiles, and by extension this also applies to Mapp Connect.

## **Leveraging Custom Attributes to Match Users**

### Use Case Example

**Scenario:** Imagine you’re managing a marketing campaign and want to unsubscribe all users associated with a specific campaign labeled as `marketing-campaign: Summer2025`. This attribute serves as a non-unique identifier, as multiple users can share the same campaign label.

**Step-by-Step Setup:**

1. **Create the Contacts:** Set up user profiles with a custom attribute `marketing-campaign` assigned to the appropriate value, such as `Summer2025`. Add these contacts to the relevant group, for instance, "Campaign Participants."
2. **Configure the Mapp Connect Integration:**
  - Go to the **Mappings** section in Mapp Connect.
  - Add the required mappings to recognize and use the custom attribute `marketing-campaign` as a non-unique identifier:
    - Map `custom_attribute_name_with_identifier` to `marketing-campaign` and set its type to `"NONE"`.
    - Map `marketing-campaign` to `marketing-campaign` and set its type to `"CUSTOM"`.
3. **Perform the Action:** Use the configured setup to send an event that unsubscribes users associated with `marketing-campaign: Summer2025` from the designated group.

**Example Event Payload:**

```json
{
  "unsubscribe": true,
  "custom_attribute_name_with_identifier": "marketing-campaign",
  "marketing-campaign": "Summer2025",
  "group": 1 // Replace with the actual group ID
}
```

**Expected Result:**

All users with the custom attribute `marketing-campaign: Summer2025` are unsubscribed from the specified group.

**Detailed Explanation of Mappings:**

Custom attribute mappings are essential for this setup. The first mapping (`custom_attribute_name_with_identifier`) ensures the system recognizes the attribute name, while the second mapping establishes the attribute as a valid non-unique identifier for processing events. Ensure that both mappings are correctly configured in your Mapp Connect instance.

## Limitation

**Related Data (RD)** subtype events are not user-based and cannot be used with the Related Data types unless the Related Data list is explicitly linked to a user profile. In such cases, you can use the User event type to update attributes linked to Related Data.

A unique identifier automatically assigned by Mapp Engage when a new contact is added to the system.

- The **Contact ID** cannot be changed or edited.
- In some parts of Mapp Cloud, this identifier may also be referred to as **User ID**, but both terms describe the same concept.
- You can find the Contact ID by going to *Audience > Contact Management > All Contacts* and checking the ID column.

In Mapp Engage, a mobile number serves as a **unique user identifier**, essential for managing contact profiles across various communication channels.

Mobile numbers in Mapp Engage must follow the international format, starting with a "+" symbol followed by the country code and the number (e.g., +49 123 455 679).