DELETE
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
/
identity
/
{alias_label_to_delete}
Delete alias
curl --request DELETE \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
{
  "identity": {
    "onesignal_id": "OneSignal-ID-in-UUID-v4-format"
  }
}

​
Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the Delete user API.

​
How to use this API

To remove an alias from a user:
  1. Identify the user via a known alias by specifying:
    • alias_label – the type of alias (e.g., email, external_id)
    • alias_id – the unique identifier for that alias
  2. Specify the alias to remove using:
    • alias_label_to_delete – the label of the alias to be deleted
    The alias_label_to_delete can be the same as the alias_label used to identify the user.
  3. This action is performed synchronously—the alias is deleted immediately after the request is processed.
The onesignal_id alias cannot be deleted. Only secondary aliases (like email, external_id, etc.) are removable.
For a full explanation of identity management, see Users and Aliases.

​
FAQ

​
Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias_label_to_delete. If you want to delete the entire user and all associated data, use the Delete user API.

​
What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal_id.

Path Parameters

​
app_id
string
required

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

​
alias_label
string
default:external_id
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.

​
alias_label_to_delete
string
required

The name of the alias to remove.

Response

200

​
identity
object