Create subscription (by alias)
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.
Overview
This API allows you to add a new subscription to an existing User using an alias identifier. A subscription reflects a user’s intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See Subscriptions for additional context.
If you’re looking to create a new user and add subscriptions simultaneously, use the Create User API instead.
How to use this API
To attach a subscription, the user must already exist and be referenced using an alias. The alias_label
and alias_id
path parameters define how the user is identified:
- Common alias:
external_id
- Other options:
onesignal_id
, or custom aliases
For details, refer to Users and Aliases.
Required Fields
Each subscription must include at least:
type
: the channel (e.g.,Email
,SMS
,iOSPush
)token
: the unique identifier for the channel (e.g., email address, phone number, push token)
If the specified type
and token
already exist in the app, the subscription will be transferred to the user identified in the path parameters.
Headers
Your App API key with prefix Key
. See Keys & IDs.
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
.