Overview
Use this API to manage user aliases by providing one known alias (such asexternal_id
, onesignal_id
, or a custom alias) and specifying additional aliases to add or update.
This endpoint focuses solely on the identity
object. If you need to fully create a user with subscriptions and properties, use the Create user API instead.
- If an alias with the same
alias_label
already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created. - Want to use a subscription instead of an alias to identify the user? Use Create alias (by subscription).
- Users – for details on OneSignal ID and External ID
- Aliases – for setting and managing custom aliases
- Delete alias – for removing aliases
How to use this API
To identify the user:- Use
alias_label
for the type of alias you know (e.g.,external_id
,onesignal_id
, or a custom alias) - Use
alias_id
for the value of that alias
We strongly recommend setting the
external_id
as your primary user identifier. This can be done through our frontend SDK’s login method when a user signs in to your app or website. It helps OneSignal associate the user’s push, email, and SMS subscriptions to a unified user identity.Headers
Your App API key with prefix Key
. See Keys & IDs.
Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The alias name or key to locate the user. Most commonly set as external_id
but can be the onesignal_id
or a custom alias.
The specific identifier for the given alias to identify the user.
Body
application/json
One or more aliases to be created for this user.
Response
200