Important: You must set an External ID before using custom aliases.OneSignal uses a unique
onesignal_id
to identify users. This ID only stays consistent across Subscriptions if they have the same external_id
.Custom aliases do not link Subscriptions together—they rely on the external_id
to work correctly. Without it, aliases won’t associate with the same user across devices or platforms.What is a custom alias?
A custom alias is akey : value
pair where:
- The
alias_label
(key) is a consistent, static identifier across all users (e.g.,facebook_id
,firebase_id
,crm_user_id
). - The
alias_id
(value) is the specific user’s ID for that label (e.g.,facebook_id: 3453443
,firebase_id: test3555
).
Why use aliases?
- Identify users across multiple platforms and databases.
- Send targeted transactional messages using the Create Message REST API.
- Fetch, update, or delete users via the User REST APIs.
How to Set Aliases
You can set aliases either using the OneSignal SDK or via the REST API.Using the SDK
Follow these steps in your app:-
Set the External ID
Call
OneSignal.login(externalId)
to associate the user record. -
Set custom aliases
Use
OneSignal.User.addAlias(label, id)
to add a single alias, orOneSignal.User.addAliases({ label1: id1, label2: id2 })
to set multiple. -
Logout (optional)
Use
OneSignal.logout()
to remove the external ID and any associated aliases for that device or session.
Using the REST API
To set custom aliases via the API, use the Create Alias endpoint. This method is typically used in backend systems for server-side user management. Example Request:Best practices
- Always set the
external_id
before assigning any aliases. - Use stable, descriptive labels (e.g.,
crm_user_id
,legacy_user_id
) to avoid confusion across teams. - Avoid using sensitive information such as email addresses or phone numbers as alias values.
- Use
logout()
to clean up aliases on device sign-out or user switch events.
Custom aliases tutorial complete!
Next steps:
- Review our Users and Subscriptions documentation if you have not already.
- Explore our REST API documentation for more details on using aliases via the API.
- Set up Integrations to sync user data across systems.