Choosing the right identifier to use as an External Entity ID is an important step in building your Alloy integration. Because External Entity IDs link the Alloy Entity back to your internal system of record (and potentially other external systems), establishing a strong mapping early on is critical.

What makes a good External Entity ID?

A strong External Entity ID is stable, unique, and tied to a verified or authenticated identity. Specifically, you should look for an identifier that:

• Does not change over the lifetime of the customer relationship. Mutable fields like email addresses or phone numbers are poor choices; they can be updated by the customer, transferred, or shared across multiple people, which can cause records to become associated with the wrong individual.

• Is unique per person or business in your system. An ID that can be shared or reused will cause entity collisions and make it difficult to track a customer's lifecycle accurately.

• Is assigned as part of a verified or authenticated event. The External Entity ID should reflect a known identity, not just a claimed one. For example, linking an Entity to a record that was verified via a completed onboarding flow is appropriate; linking it based solely on user-supplied PII that hasn't been confirmed is not.

Common Approaches

Post-Onboarding Assignment

Many financial institutions rely on an identifier that is assigned by a core or back-office system only after initial account opening is complete. These identifiers are typically derived from or linked to the customer's tax ID (SSN or EIN), making them an effectively immutable reference to a real-world identity. Because they aren’t known at the start of onboarding for net-new customers, it’s common to send new onboarding Journey Applications without an External Entity ID specified, then retroactively assign the identifier once it has been issued in your internal systems.

Pre-Onboarding Registration

Another common pattern some institutions follow is to create an online user account at the very start of the customer journey, before any financial account onboarding begins, and use that identifier as the Alloy External Entity ID. This is also an acceptable pattern, provided that the user authenticates with that identifier before subsequent Alloy's onboarding flow begins. When authentication comes first, you can be confident the External Entity ID maps to a known, authenticated identity rather than an unverified claim.

Note: Using a PII element like email address to recognize a potential existing user during an unauthenticated onboarding flow is not uncommon, but it should always trigger re-authentication before the individual is treated as a confirmed existing Entity. Your data model should still allow authenticated users to update their profile information gracefully without impacting their assigned identifier.

Handling Uncertain Identities

In cases where you are not yet sure whether a person interacting with your system is an existing customer or a new one, treat them as a new Entity. Create a new Entity record without an External Entity ID, run them through your onboarding or verification flow, and if you subsequently confirm they are the same person as an existing customer, you can use Entity Merging to consolidate the records. Alloy will carry over all history and activity from both records into the merged Entity.

Do not attempt to preemptively link a new Entity to an existing one based on matching PII alone. Matching name, email, or even SSN is not sufficient to confirm identity without verification or authentication. Suspected linked entities and confirmed linked entities are meaningfully different, and your decisioning logic should treat them accordingly.

Why does this matter?

Defining Entity identities is ultimately your institution's responsibility. Alloy can store, track, and act on your customer data, but the definition of what constitutes a unified customer in your system must map to your own account and regulatory definitions. Regulators expect financial institutions to maintain a coherent, deduplicated customer record, and Alloy's Entity model is designed to support that.