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 'Content-Type: application/json' \
  --data '{
  "identity": {
    "external_id": "test_external_id",
    "onesignal_id": "<string>"
  }
}'
"{\n    \"identity\": {\n        \"onesignal_id\": \"ONESIGNAL_ID\",\n        \"test\": \"test\"\n    }\n}"

​
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

​
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
application/json

200

​
identity
object