An identifier is a value Insider One uses to recognize the same person across sessions, devices, and channels: an email address, phone number, UUID, or a custom ID from your own system. An attribute is a value Insider One stores about a person but never uses to recognize them: birthday, loyalty tier, last product viewed. The distinction matters because the identifiers object is the only place Insider One looks when deciding whether an incoming request belongs to an existing profile, a new one, or should be merged into one. Get the placement right, and Insider One recognizes returning users, keeps their profiles unified, and processes requests cleanly. Send the wrong value to the wrong object, or misconfigure Identity Resolution Management (IRM) settings, and Insider One does exactly what it was configured to do: it will not match a value it was never told to recognize, so a returning user can go unidentified, the data can be stored without ever being used for matching, or the request can be rejected outright. Most of the validation errors developers hit when integrating with Insider One trace back to this one distinction.
Identifiers vs. attributes
Insider One stores everything it knows about a person in a single Unified Customer Database (UCD) profile: identifiers, attributes, and events. All three describe the user, but only one of them is allowed to decide who the user is.
Identifiers | Attributes & Events | |
|---|---|---|
Purpose | Recognize and unify a profile across channels and devices | Describe or record what a profile did or has: used for personalization, segmentation, and reporting |
Used for matching? | Yes, checked against the UCD to create, update, or merge profiles | No, never consulted during identity resolution, regardless of value |
Must be unique? | Yes, each identifier value can belong to only one profile at a time | No, any number of profiles can share the same attribute value |
Examples | Email, phone number, UUID, custom CRM/CDP ID | Birthday, gender, loyalty tier, city, last order value |
When a user first browses anonymously, Insider One creates an anonymous UCD profile and tracks interactions against it. The moment an identification request carries a recognized identifier, Insider One searches the UCD for a match: no match converts the anonymous profile into a known one; a match merges the incoming data into the existing profile. Everything else in the request, attributes and events, rides along and gets stored, but plays no part in that matching decision.
Why identifiers must live in the identifiers object, never in attributes or events
Identification and Upsert requests to Insider One separate payload fields into three buckets: identifiers, attributes, and events. Only fields placed in the identifiers object are ever evaluated for identity resolution. A value that uniquely names a person (email, phone, UUID, external ID) does nothing to unify that person's activity if it is sent as an attribute instead: Insider One stores it, but never uses it to recognize the same person again next time they show up under a different session.
Placement in the identifiers object is necessary but not sufficient. A field also has to clear the identifier configuration in IRM before it counts:
It must be one of the identifier types enabled on the Identity Resolution page: anything sent as an identifier but not on that list is ignored for matching purposes.
It must not be paused.
It must not match a blocked value (placeholders such as “undefined,” “anonymous,” “0,” “1,” or “null”).
It must fit within the configured value limit for that identifier type, or priority rules decide which value wins.
Get this wrong in either direction, and the failure is quiet, not loud:
Identifying values sent as attributes: the same person accumulates multiple disconnected profiles. Personalization breaks, campaigns under- or over-send, and channel-specific issues follow. For example, when phone number isn’t configured as an identifier for WhatsApp, users who share a number can receive duplicate messages, and click, reply, and unsubscribe events can be attributed to the wrong profile entirely.
Non-identifying or unstable values sent as identifiers: they consume slots in a list capped at 10 identifier types, risk unintended merges because identifier values must be unique per profile, and, if predictable or guessable, like sequential IDs or a client-side value an attacker can forge, create a data-integrity and privacy exposure.
Malformed identifier values: inconsistent formatting is a frequent, request-level failure. Phone numbers should always be sent in E.164 format (for example, +905551234567); “505…” and “+905…” can be treated as different values and quietly create separate profiles instead of one.
IRM best practice
Use a unique, non-guessable value your own system generates (a CRM or CDP person ID) as the priority-1 identifier with a value limit of 1, and keep client-supplied values like email and phone as attributes unless you specifically need them for identity resolution. This avoids exposing identity matching to values a user, or an attacker, can guess or alter.
How IRM settings govern which identifier types are active
Identity Resolution Management is configured under Components > Identity Resolution, typically set up with Insider One during onboarding; changes afterward go through the Insider One team. Insider One supports Email, Phone Number, and UUID as default identifier types, plus custom identifiers, up to 10 total. Five controls determine how each one behaves:
Identifier list
Only identifier types added to this list are considered during identification requests. An identifier value sent in a request but not enabled here is not used for matching.
Priority
Priority (1 = highest) defines which identifier is checked and trusted first. When an incoming request's identifiers point at different existing profiles, or would otherwise breach a value limit, priority breaks the tie: Insider One follows the higher-priority identifier and disregards the lower-priority one for that request. Because of this, the priority-1 identifier should almost always carry a value limit of 1; otherwise incorrect profile merges become possible.
Value limit
The value limit caps how many values of one identifier type a single profile can hold (maximum 100; 1 is recommended for most identifier types). Only the most recently set value is “active”: indexed for segmentation and shown in the profile panel. Older, “inactive” values are retained only so a future request bearing that old value can still resolve to the right profile; they are not usable for targeting. Raising the limit does not give you multiple usable values for one profile. To correct or replace a value, use the Update User Identifiers or Delete User Identifiers APIs instead.
Blocked values
Blocked values are rejected outright when submitted as identifiers, which prevents an entire user base from accidentally merging into one profile through a shared placeholder (a hardcoded “anonymous@yourbrand.com” in a buggy integration is the classic case).
Pause
Pausing an identifier tells Insider One to stop using it in identification requests without removing its configuration. This is useful when an integration is found to be sending malformed values and needs a fix before it resumes affecting the UCD.
Together, priority and value limits determine one of three outcomes for every identification request: profile creation (no existing profile matches the priority-1 identifier), profile update (exactly one profile matches, no conflicting lower-priority matches), or profile merge (the priority-1 identifier matches one profile while a lower-priority identifier matches a different one, and combining them stays within all configured limits). If a merge would exceed a limit, it is rejected, and the profiles involved are left unchanged rather than partially combined.
Email-as-identifier vs. email-as-attribute
Email illustrates the identifier/attribute distinction concretely because Insider One supports both roles for it, with different consequences for messaging and reachability.
Email as the identifier (default)
Each profile is tied to exactly one active email address. Subscribing, unsubscribing, and reachability status are unambiguous because they resolve to a single profile per address; no additional logic is required. This is the simplest setup and fits straightforward newsletter and promotional use cases.
Email as an attribute (identifier is UUID or a custom ID)
When email is not the identifier, more than one profile can legitimately share the same email address, common in B2B accounts, shared inboxes, or multi-brand and multi-region setups where the same address maps to distinct customer relationships. Because reachability can no longer be resolved from the email address alone, Insider One offers two explicit flows:
Profile-based subscription flow: each profile keeps an independent opt-in and reachability status, even when several profiles share an email address. Unsubscribing on one profile does not affect the others.
Email-based subscription flow: subscription status is tracked at the email-address level. Unsubscribing on any profile that shares that address unsubscribes all of them.
Only one flow can be active per account, and it is set deliberately with the Insider One team; it is not something to change casually once campaigns are running. The API surface differs accordingly: when email is the identifier, standard Data Governance APIs take the email address directly; under either non-email flow, only UUID is accepted by the unsubscribe/resubscribe and suppression endpoints, even if other custom identifiers are configured for the account.
When to use insider_id directly
Every UCD profile carries a permanent, system-generated Insider ID (surfaced as “Profile ID” in User Profiles and in API responses). It sits outside the identifiers object entirely: it is not something a user provides, and it is never subject to IRM priority, value-limit, or blocked-value rules. Reach for it directly, instead of resolving through the identifiers object, when you already know exactly which profile you mean and want to eliminate any chance of Insider One making a different matching decision:
Correcting or removing a specific profile's identifier values through the Update User Identifiers or Delete User Identifiers APIs.
Backend or support tooling that looks up a single, already-known profile against the UCD profile endpoint, rather than asking Insider One to resolve one.
Any server-side operation where triggering a merge would be unacceptable: insider_id addresses one exact profile with certainty, sidestepping resolution logic altogether.
The rule of thumb: send identifiers when you want Insider One to figure out which profile a person belongs to; use insider_id when you already know, and you want that certainty preserved.
Checklist: avoiding identifier-related errors
Identifying values (email, phone, UUID, custom ID) go in the identifiers object, never in attributes or events.
Confirm the identifier type is enabled, unpaused, and not blocked on the Identity Resolution page before relying on it for matching.
Keep the priority-1 identifier's value limit at 1 to prevent incorrect merges.
Format identifiers consistently across every source: phone numbers in E.164 (+countrycode...) at minimum.
Avoid placeholder or predictable values (“null,” “0,” sequential IDs) as identifiers; add known bad values to Blocked Values.
Use insider_id, not the identifiers object, when a backend process already knows the exact profile it needs to touch.
Treat the email-as-identifier decision as a long-term architectural choice; changing it later affects subscription and reachability logic across the account.
Choose your identifiers: questions to work through first
These questions are meant to guide a discovery conversation, not to produce a configuration automatically. A “yes” to one of them can still be overridden by a constraint another one surfaces, so answering the list in order is not the same as arriving at your IRM setup. The point is to force a broader evaluation across your login flow, your other systems, and your data-sharing constraints, rather than defaulting to the first identifier that comes to mind because it is already familiar: “we use email for login, so let’s just use that.”
Authentication and tracking model
Question | What to consider |
|---|---|
How do users log in to your platform? (email, phone, username, social login, or a combination) | This usually points to a natural default identifier, but the login method is not automatically the right identifier. Confirm the login value is actually sent to Insider One on every relevant event, not only at sign-in. |
Is this login value fixed for the lifetime of the account, or can it change? | Email and phone number can both change. If the identifier changes, prior activity can become orphaned unless a stable secondary identifier, such as an internal user ID, carries continuity across the change. |
Do you need to track anonymous, not-yet-registered users? | If yes, plan how anonymous browsing history gets connected to the known identifier at sign-up or sign-in, and what should happen to activity recorded before that point. |
Do the same users log in from more than one device? Are you expecting cross-device recognition? | Cross-device recognition depends entirely on the same identifier value reaching Insider One from every device and channel. If devices use different login methods, decide how those will be connected, or accept that they remain separate profiles until they are. |
Existing systems and data-sharing constraints
Question | What to consider |
|---|---|
Is your e-commerce stack Shopify or Magento? | Platform choice affects which identifiers arrive automatically through native integrations, which ones you must send manually, and what customer ID the platform itself treats as canonical. |
Do you have a CRM (Salesforce, HubSpot, in-house)? What does it call the user ID there? | If Insider One profiles eventually need to reconcile with CRM records, the CRM's user ID may need to become an identifier, or at least a synced attribute. Check its uniqueness and lifecycle guarantees before giving it identifier status. |
Do you have a loyalty or membership program? Is there a card number or membership number? | A loyalty ID often looks like an ideal identifier, but confirm it can actually leave the loyalty system. Some membership IDs carry contractual or regulatory restrictions that prevent sharing them outside their originating system, which rules them out regardless of how well they otherwise fit. |
Are you migrating from a legacy system? Will old user IDs carry over? | If historical IDs will not migrate cleanly, decide in advance whether historical profiles get recreated, merged, or left disconnected from new activity, rather than discovering the gap after go-live. |
Do you have a mobile app? Is the ID used in-app the same as on the web? | Unification only works if the same identifier value is sent from both. If the app and web use different login systems or ID generation, that mismatch needs to be resolved before cross-platform identity is possible. |
Which of these IDs can actually be sent to the UCD on every event? | This question overrides all the others. An identifier can be technically ideal and still unusable if it cannot legally, contractually, or technically be included on every event payload. This is what turns the answers above into decisions you can actually implement. |
Why the last question matters more than it looks:
A “yes” earlier in this list is not the finish line. A team can correctly answer “yes, we have a loyalty program with a membership number” and still be unable to use it, for example because that ID is confidential and cannot be shared outside the loyalty system for regulatory reasons. The membership number was real, unique, and available in principle; it simply could not travel with event data. Any identifier candidate needs to clear both questions, not just the one that made it look appealing.
Work through this list with product, engineering, and whoever owns data governance or compliance before finalizing IRM settings. Treat it as a discovery exercise with real trade-offs to weigh, not a form that resolves itself the moment the first familiar answer, such as “we already use email for login,” shows up.