Create or update alias
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.
Overview
Use this API to manage user aliases by providing one known alias (such as external_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).
See also:
- 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.
Changes to the identity object take effect immediately upon request.
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
Response
200
The response is of type object
.