Skip to main content
PATCH
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
/
identity
Create or update alias
curl --request PATCH \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identity": {
    "external_id": "test_external_id",
    "onesignal_id": "<string>"
  }
}
'
{
  "identity": {
    "onesignal_id": "OneSignal-ID-in-UUID-v4-format",
    "custom_alias_label": "the-users-custom-alias-id"
  }
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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. Alias keys (alias_label) and values (alias_id) are each limited to 128 characters. A user can have up to 10 custom aliases total.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key . See Keys & IDs.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
alias_label
string
required

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.

​
alias_id
string
required

The specific identifier for the given alias to identify the user.

Body

application/json
​
identity
object

One or more aliases to be created for this user.

Response

200

​
identity
object