Ingestion by External Identifier

Use the Ingestion by External Identifier API to update user profiles and ingest events when your system does not have the WebEngage User ID (Customer Unique ID or CUID).

Instead of identifying users by their WebEngage User ID, this API lets you identify them using a supported system or custom user attribute, such as an email address, phone number, or loyalty ID. WebEngage resolves the identifier to the corresponding user internally before applying profile updates and recording events.

This API is useful for integrating offline systems, CRMs, POS systems, payment gateways, or third-party applications that recognize users through alternate identifiers.

When to Use This API

Use this API when:

Your application does not have access to the WebEngage User ID.
Users are identified using another unique attribute, such as email, phone number, or a custom identifier.
You want to update user attributes and/or ingest events without performing a separate user lookup.

Example

A retail POS system records an offline purchase using the customer's phone number. Since the POS does not know the customer's WebEngage User ID, it can use the phone number as the external identifier to associate the purchase with the correct user profile.

Supported External Identifiers

The API supports the following identifiers:

Limitations

The following attribute types cannot be used as external identifiers:

• Boolean
• Date
• List
• Object

Request Details

Method

POST

Endpoint

/v2/accounts/{licenseCode}/users/by-external-identifier

Authentication

Bearer <API_KEY>

Content-Type

application/json

Request Parameters

User Profile Updates

The userDetails object follows the same format as the existing Track Users API.

You can update any supported user attributes while identifying the user through an external identifier.

Event Ingestion

The events array follows the same schema as the existing Track Events API.

Each request can contain up to 25 events.

Phone Number Matching

To improve user matching, WebEngage automatically normalizes phone numbers before performing the lookup.

For example, if the request contains:

+919876543210

WebEngage attempts matching using:

• +919876543210
• 919876543210
• 9876543210

If the account uses automatic hashing or ZeroPII, each normalized value is hashed before matching.

Hashing and ZeroPII

WebEngage supports different account configurations when matching email addresses and phone numbers.

Automatic Hashing

If automatic hashing is enabled, raw email addresses and phone numbers are hashed internally before lookup.

Self-Hashed Accounts

For accounts that manage hashing externally, provide:

• hashed_email
• hashed_phone

No additional hashing is performed.

ZeroPII Accounts

For ZeroPII-enabled accounts, WebEngage hashes raw email addresses and phone numbers using SHA-256 before matching. Alternatively, you can provide pre-hashed values directly.

Multiple User Matches

If an external identifier matches multiple users, the API updates all matching users.

If more than 10 users match the identifier, WebEngage processes only the 10 most recently active users, ordered by last_seen (or created_at when last_seen is unavailable).

Rate Limits