External IDs

External IDs are unique identifiers assigned to a user by an external platform — such as a CRM, ad platform, or e-commerce system. They act as a bridge between CustomerLabs and those platforms, enabling the system to recognize the same user across different tools and data sources.

Why External IDs Are Necessary

CustomerLabs unifies data from multiple sources — websites, apps, CRMs, offline files — into a single customer profile. For this unification to work correctly, the system needs a reliable way to match a user in one source to the same user in another.

User traits like email and phone are the primary identifiers for this. But in many real-world scenarios:

• A user interacts anonymously before providing their email
• A CRM assigns its own internal ID that doesn’t map to email
• An ad platform like Meta or Google has its own click or browser ID for the user
• A user may be identified differently across multiple integrations

External IDs handle these cases. They attach additional, platform-specific identifiers to a user’s profile without replacing the primary identity. This gives CustomerLabs more signals to connect the dots and maintain a clean, unified profile.

Note

Without External IDs, cross-platform user matching relies solely on shared user traits (email, phone). External IDs expand the resolution surface, reducing identity gaps across sessions and platforms.

How External IDs Work

External IDs are passed as part of the external_ids object inside customProperties when an event or identify call is made. CustomerLabs attaches these IDs to the unified user profile.

They are used in two ways:

1. Cross-platform association — Link the CustomerLabs user profile to a user record in another platform (e.g., CRM user ID, Google Analytics client ID)
2. Alternate identify-by keys — Act as identifiers in identify calls when a standard identifier (email or phone) is not available

For the full syntax and code examples, see the Event Schema — External IDs reference.

External IDs and the 360-Degree Profile

External IDs are stored persistently in the user’s 360-degree profile in CustomerLabs — not in a browser cookie.

This is significant because browser cookies are unreliable:

• Browsers clear the cookies after a certain period of time (For example, Safari’s Intelligent Tracking Prevention (ITP) deletes the cookies after 24 hours, and Chrome deletes the cookies after 7 days)
• Privacy-focused browsers (Brave, Firefox with Enhanced Tracking Protection) restrict or block cookies
• Users can manually clear cookies at any time

When a cookie is cleared, identifiers like click IDs (_fbp, _fbc) and session tokens that were stored in the browser are lost. However, because CustomerLabs has already persisted these External IDs in the user’s 360-degree profile, they are retained server-side.

When a subsequent event is triggered by that user, CustomerLabs can look up their unified profile and re-attach those External IDs — including click IDs and platform-specific identifiers — before sending the event to ad platforms. This ensures attribution is not broken even if the user’s browser environment has changed.

Note

This persistence means a purchase event fired weeks after the original ad click can still carry the original _fbp or _fbc stored in the user’s profile — enabling accurate attribution even across cookie-clearing intervals.

External Ids in CustomerLabs

Reserved External ID Keys

CustomerLabs recognizes the following reserved keys out of the box:

Key	Description
customerlabs_user_id	CustomerLabs internal user identifier
identify_by_email	Used to identify a user by their email address
identify_by_phone	Used to identify a user by their phone number
shopify_cart_token	Shopify cart session token
facebook__fbp	Meta (Facebook) browser pixel ID (_fbp)
google_analytics__client_id	GA4 client identifier
facebook_lead_id	Lead ID from Meta Instant Forms

Caution

Reserved External ID keys should not be renamed. If a reserved key is changed, CustomerLabs will not be able to correctly associate the identifier with the respective platform or process it during data activation.

Custom External IDs

In addition to reserved keys, you can pass any custom identifier as an External ID. These are stored and attached to the user’s profile in CustomerLabs.

Common examples:

• crm_id — Internal ID from your CRM system
• lead_id — Identifier from a lead management tool
• user_id — Application-level user identifier

Custom External IDs are useful when you need to reference a CustomerLabs user profile from an external system, or when you want to use a platform-specific ID to resolve user identity across data sources.

Note

Custom External IDs are attached to the user profile and can be used as alternate identifiers in identify calls.

External IDs and Ad Algorithms

When CustomerLabs sends events to ad platforms, it includes External IDs alongside hashed user traits. For Meta (Facebook), this includes platform-native identifiers like facebook__fbp and facebook_lead_id, which Meta uses to match the event to a user in its system.

In addition, CustomerLabs sends customerlabs_user_id as an external identifier to Meta. From Meta’s perspective, this is an external ID that belongs to a different system (CustomerLabs). When every event across the user’s entire funnel — from the first page view to the final purchase — carries the same customerlabs_user_id, Meta can:

• Recognize all those events as belonging to the same user
• Build a complete picture of the user’s journey
• Train its algorithm more accurately on what a high-intent or converting user looks like

This consistent identity signal across the funnel improves the quality of data that Meta’s algorithm learns from, which leads to better targeting, lower CPAs, and improved Event Match Quality (EMQ).

Note

Consistency is key. If the same user is represented by different or missing External IDs at different funnel stages, the ad platform treats them as separate users — fragmenting the signal and reducing algorithm effectiveness.

Benefits

Benefit	Description
Stronger identity resolution	More identifiers mean fewer gaps when matching users across sessions, devices, and platforms
Cookie-resilient attribution	External IDs are stored in the 360-degree profile server-side — click IDs and session tokens persist even after browsers clears cookies or users clear their browser data
Consistent funnel identity	Sending the same customerlabs_user_id across all funnel events lets ad platforms recognize the full user journey and train more accurately
Cross-platform associations	Link CustomerLabs profiles to records in your CRM, ad platform, or other tools
Richer unified profiles	Each External ID adds another dimension to the 360-degree profile, improving data completeness
Improved ad matching	Sending platform-native IDs (like facebook__fbp) alongside user traits increases Event Match Quality (EMQ) on ad platforms
Flexible identification	When email or phone is unavailable, a custom External ID can serve as the fallback identifier in an identify call