Identifiers
Every user in your request must include at least one primary identifier so RevBridge can link events to the correct customer profile.
Primary identifiers
At least one of these is required per user:
| Identifier | Type | Description |
|---|
user_id | string | Your internal user or customer ID |
email | string | The user’s email address |
phone_number | string | Phone number in E.164 format (e.g., +5511999887766) |
anon_id | string | An anonymous identifier for users who haven’t signed up yet |
If none of these four identifiers are provided, the user will be rejected with a validation error.
Additional identifiers
You can also include device and advertising identifiers:
| Identifier | Type | Description |
|---|
idfa | string | Apple Identifier for Advertisers |
adid | string | Google Advertising ID |
Identity resolution
RevBridge uses deterministic identity resolution to automatically unify customer profiles across all your data sources — API events, CSV imports, and integrations like Shopify.
When you send an event with identifiers, RevBridge:
- Looks for an existing profile that matches any of the provided identifiers.
- If a match is found, the event is linked to that profile, and any new identifiers are added.
- If multiple profiles match (e.g., one matched by email, another by phone), they are automatically merged into a single unified profile.
- If no match exists, a new profile is created.
Merge keys
Not all identifiers trigger a merge. RevBridge distinguishes between merge keys (which can unify two separate profiles) and identification keys (which can only recognize an existing profile):
| Identifier | Merge key | Behavior |
|---|
email | Yes | Two events with the same email = same person |
phone_number | Yes | Two events with the same phone = same person |
user_id | Yes | Two events with the same user_id = same person |
anon_id | No | Identifies a device/session, but won’t merge two people |
idfa / adid | No | Identifies a device, but won’t merge two people |
Providing multiple identifiers (e.g., both email and user_id) improves matching accuracy and enables cross-source merging. When a user logs in and you know both their anonymous ID and their real identity, send all identifiers together.
Example 1: Progressive profile enrichment
A user first browses anonymously, then logs in, then makes a purchase from a different channel. RevBridge automatically builds the complete profile:
Event 1: Anonymous browsing
{
"identifiers": { "anon_id": "device_abc123" },
"events": [{ "event_name": "page_view", "page": "/summer-sale" }]
}
Event 2: User logs in — links anonymous activity to known identity
{
"identifiers": {
"anon_id": "device_abc123",
"email": "jane@example.com",
"user_id": "usr_001"
},
"events": [{ "event_name": "login" }]
}
Event 3: Purchase via SMS link — adds phone to same profile
{
"identifiers": {
"phone_number": "+5511999887766",
"email": "jane@example.com"
},
"events": [{ "event_name": "purchase", "revenue": 129.90 }]
}
anon_id, email, user_id, and phone_number. All events appear in the same timeline.
Example 2: Cross-source merge
A customer is imported via CSV with only a phone number. Later, an API event arrives with the same phone and an email. RevBridge automatically merges them:
CSV import: phone: +5511999887766 → Profile created
API event: email: jane@example.com, phone: +5511999887766 → Same profile, email added
Example 3: Shared identifiers
When multiple people share a phone number (e.g., a family phone), events with that phone are merged into the same profile. This is the default behavior since phone is a merge key.
email: maria@gmail.com, phone: +5511982299869 → Profile created
email: joao@gmail.com, phone: +5511982299869 → Merged into same profile
If shared phone numbers are common in your use case, contact support to configure phone as a non-merge key for your account.
Data isolation
Identity resolution is fully isolated per account. The same email address used by two different RevBridge customers will never be merged across accounts. Each account has its own independent identity resolution.
User profile fields
Beyond identifiers, you can send profile attributes in the identifiers object. These fields are attached to the customer profile and can be used for segmentation and personalization.
| Field | Type | Description |
|---|
first_name | string | First name |
last_name | string | Last name |
gender | string | Gender |
birthday | string | Date of birth (e.g., 1990-05-20) |
age | number | Age (must be a numeric value) |
language | string | Preferred language (e.g., pt-BR, en-US) |
timezone | string | IANA timezone (e.g., America/Sao_Paulo) |
Location
| Field | Type | Description |
|---|
city | string | City name |
country | string | ISO 3166-1 country code (e.g., BR, US) |
Technical context
| Field | Type | Description |
|---|
platform | string | Platform (e.g., web, ios, android) |
ip_address | string | User’s IP address |
user_agent | string | Browser or app user agent string |
carrier | string | Mobile carrier |
device_model | string | Device model (e.g., iPhone 15 Pro) |
os_version | string | Operating system version |
app_version | string | Your application version |
Consent flags
RevBridge tracks channel-level consent using a 3-state model to ensure campaigns only reach users who have explicitly opted in. Send these as part of the identifiers object.
| Value | Meaning | Campaign behavior |
|---|
true or 1 | Opt-in — user has given consent | Eligible for campaigns on this channel |
false or 0 | Opt-out — user has explicitly revoked consent | Excluded from campaigns on this channel |
Not sent / null | Not informed — no consent data yet | Excluded from campaigns (conservative default) |
| Field | Type | Description |
|---|
email_opt_in | boolean | User has opted in to receive emails |
sms_opt_in | boolean | User has opted in to receive SMS |
whatsapp_opt_in | boolean | User has opted in to receive WhatsApp messages |
rcs_opt_in | boolean | User has opted in to receive RCS messages |
web_push_opt_in | boolean | User has opted in to web push notifications |
mobile_push_opt_in | boolean | User has opted in to mobile push notifications |
gdpr_consent | boolean | User has given GDPR consent |
Send consent flags whenever they change — for example, when a user subscribes to your newsletter or updates their communication preferences. The distinction between “not informed” and “opt-out” matters: a user who has never been asked is different from one who explicitly declined.
Custom attributes
Any fields in the identifiers object that are not listed above are stored as custom attributes on the user profile. This lets you attach any business-specific data.
{
"identifiers": {
"email": "jane@example.com",
"user_id": "usr_001",
"first_name": "Jane",
"loyalty_tier": "gold",
"company": "Acme Inc",
"signup_source": "google_ads"
},
"events": [
{ "event_name": "purchase", "revenue": 59.90 }
]
}
Complete example
A request with full profile data, consent flags, and custom attributes:
{
"users": [
{
"identifiers": {
"user_id": "usr_001",
"email": "jane@example.com",
"phone_number": "+5511999887766",
"first_name": "Jane",
"last_name": "Smith",
"gender": "female",
"birthday": "1992-03-15",
"age": 33,
"language": "pt-BR",
"timezone": "America/Sao_Paulo",
"city": "São Paulo",
"country": "BR",
"platform": "web",
"email_opt_in": true,
"sms_opt_in": true,
"whatsapp_opt_in": false,
"loyalty_tier": "gold"
},
"events": [
{
"event_name": "purchase",
"timestamp": "2026-01-15T14:30:00Z",
"revenue": 259.90,
"currency": "BRL",
"order_id": "ORD-12345"
}
]
}
]
}
