Skip to main content
DELETE
cURL

Overview

Remove a specific alias from a user’s identity without deleting the user. Subscriptions and the core user record stay intact. To delete a user along with all their aliases and subscriptions, use the Delete user API instead.

How to use this API

  1. Identify the user by a known alias:
    • alias_label: the type of alias, for example onesignal_id or external_id.
    • alias_id: the value for that alias.
  2. Specify the alias to remove with alias_label_to_delete. It can be the same as the alias_label used to identify the user.
Removals are synchronous and take effect as soon as the request returns.
The onesignal_id alias cannot be removed. Only secondary aliases (like external_id or a custom alias) can be removed with this API.
For a full explanation of identity management, see Users and Aliases.

FAQ

Can I remove the same alias I used to look up the user?

Yes. This is common when an alias was set incorrectly and needs to be removed. Pass the same alias as both alias_id (to locate the user) and alias_label_to_delete (to remove it). To delete the entire user record instead of a single alias, use the Delete user API.

What happens if I remove every alias on the user?

The onesignal_id alias is permanent and can’t be removed, so the user always retains at least that one. After you remove every other alias, the user and their subscriptions stay linked to the onesignal_id.

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
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