OneSignal
App · 18 actions
Manage OneSignal users, subscriptions, segments and message templates, and read notifications, clicks and deliveries.
Actions
| Action | What it does |
|---|---|
| Add subscription | Add an email address or phone number to an existing user so you can message them there. |
| Add user alias | Give a user another id of your own, such as a CRM id, so you can find them by it later. |
| Create or update user | Create a user by your own external ID, with tags and an email address or phone number to message. |
| Create template | Create a reusable push, email or SMS message template. |
| Delete subscription | Delete one subscription. |
| Delete template | Delete a template. |
| Delete user | Delete a user and all of their subscriptions. |
| Delete user alias | Remove one of a user's extra ids. |
| Get app | Get the connected OneSignal app: its name, how many users can receive messages, and which channels (push, email, SMS) are on. |
| Get outcomes | Get totals for clicks, confirmed deliveries, unsubscribes and sessions over the last hour, day or month. |
| Get template | Get one template with its full content. |
| Get user | Get a user by their external ID or OneSignal ID, with their tags, language, ids and every subscription. |
| List notifications | List the app's notifications, newest first, with their delivery counts. |
| List segments | List the app's segments (groups of users that messages can be sent to), including OneSignal's built-in ones. |
| List templates | List the app's message templates, optionally only push, email or SMS. |
| Update subscription | Change a subscription's email address or phone number, or turn it on or off. |
| Update template | Rename a template or change its content. |
| Update user | Change a user's tags, language, country or time zone. |
Add subscription
Add an email address or phone number to an existing user so you can message them there.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Type
subscription_typetextRequired - Whether this is an email address or a phone number.One of:
Email(Email address),SMS(Phone number (SMS)). - Email or phone number
tokentextRequired - The email address, or the phone number with its country code, like +15555555555.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID). - Enabled
enabledtrue/false - Whether they can be messaged. Defaults to on.
Outputs
subscriptionobject- The new subscription
Example output
{
"subscription": {
"app_id": "11111111-2222-4333-8444-555555555555",
"app_version": "",
"device_model": "",
"device_os": "",
"enabled": true,
"id": "2c44505f-9b3d-4726-8b92-982807e42f38",
"notification_types": 1,
"sdk": "",
"session_count": 0,
"token": "jo@example.com",
"type": "Email"
}
}Add user alias
Give a user another id of your own, such as a CRM id, so you can find them by it later.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Alias name
new_labeltextRequired - What kind of id this is, such as crm_id.
- Alias value
new_idtextRequired - The id itself.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID).
Outputs
identityobject- All of the user's ids, by label
Example output
{
"identity": {
"crm_id": "c-1",
"external_id": "customer-1234",
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed"
}
}Create or update user
Create a user by your own external ID, with tags and an email address or phone number to message. If a user already has that external ID, they are updated instead.
Inputs
- External ID
external_idtextRequired - The id your own system uses for this user.
- Email address
emailtext - Adds an email subscription so you can email them.
- Phone number
phone_numbertext - Adds an SMS subscription. Include the country code, like +15555555555.
- Tags
tagsobject - Your own keys and values to keep on the user, for segments and personalised messages. Set a tag to an empty value to remove it.
- Language
languagetext - The user's language code, such as en, fr or pt-BR.
- Country
countrytext - The user's two-letter country code, such as US.
- Time zone
timezone_idtext - The user's time zone, such as America/New_York.
- Other IDs
aliasesobject - More ids for the user, each with a name, such as a CRM id.
Outputs
external_idtext- The user's external ID, empty if none
identityobject- All of the user's ids, by label
onesignal_idtext- The user's OneSignal ID
propertiesobject- Tags, language, country and time zone
subscriptionslist- The user's subscriptions
Example output
{
"external_id": "customer-1234",
"identity": {
"external_id": "customer-1234",
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed"
},
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed",
"properties": {
"country": "US",
"language": "en",
"tags": {
"plan": "pro"
}
},
"subscriptions": [
{
"app_id": "11111111-2222-4333-8444-555555555555",
"app_version": "",
"device_model": "",
"device_os": "",
"enabled": true,
"id": "2c44505f-9b3d-4726-8b92-982807e42f38",
"notification_types": 1,
"sdk": "",
"session_count": 0,
"token": "jo@example.com",
"type": "Email"
}
]
}Create template
Create a reusable push, email or SMS message template. Fill in the fields that fit the channel you choose.
Inputs
- Name
nametextRequired - The template's name, shown in OneSignal.
- Channel
channeltext - What the template sends. Defaults to push.One of:
push,email,sms. - Message
messagetext - The text of a push or SMS template.
- Title
headingtext - The title of a push template.
- Subject
subjecttext - The subject line of an email template.
- Body
bodytext - The content of an email template, as HTML.
- Preview text
preheadertext - The short text shown after the subject in an inbox.
- Link
urltext - A web address a push template opens when tapped.
Outputs
templateobject- The template with its content
Example output
{
"template": {
"channel": "push",
"content": {
"contents": {
"en": "Your order has shipped."
},
"headings": {
"en": "Shipped"
}
},
"created_at": "2026-11-13T18:17:36.771Z",
"id": "6dbb3101-c1e3-4ded-aae6-f74a3b0b61b5",
"name": "Order shipped",
"updated_at": "2026-11-13T18:17:36.779Z"
}
}Delete subscription
Delete one subscription. The user and their others stay.
Inputs
- Subscription ID
subscription_idtextRequired - The subscription's id, from 'Get user' (each entry in its subscriptions) or 'Add subscription'.
Outputs
deletedtrue/false- Always true once deleted
subscription_idtext- The subscription deleted
Example output
{
"deleted": true,
"subscription_id": "2c44505f-9b3d-4726-8b92-982807e42f38"
}Delete template
Delete a template. Messages already sent from it are not affected.
Inputs
- Template
template_idtextRequired - The template. Pick one, or give its id from an earlier step.
Outputs
deletedtrue/false- Always true once deleted
template_idtext- The template deleted
Example output
{
"deleted": true,
"template_id": "6dbb3101-c1e3-4ded-aae6-f74a3b0b61b5"
}Delete user
Delete a user and all of their subscriptions. This cannot be undone.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID).
Outputs
alias_idtext- The id the user was found by
deletedtrue/false- Always true once deleted
onesignal_idtext- The deleted user's OneSignal ID
Example output
{
"alias_id": "customer-1234",
"deleted": true,
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed"
}Delete user alias
Remove one of a user's extra ids. Their OneSignal ID stays.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Alias name
label_to_removetextRequired - The kind of id to remove, such as crm_id.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID).
Outputs
identityobject- The user's ids that remain, by label
Example output
{
"identity": {
"external_id": "customer-1234",
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed"
}
}Get app
Get the connected OneSignal app: its name, how many users can receive messages, and which channels (push, email, SMS) are on.
Inputs
None.
Outputs
appobject- The connected app
Example output
{
"app": {
"channels": {
"push": {
"enabled": true,
"platforms": [
"ios"
]
}
},
"created_at": "2026-11-12T20:26:37.710Z",
"id": "11111111-2222-4333-8444-555555555555",
"messageable_players": 98,
"name": "Lodol App",
"organization_id": "22222222-3333-4444-8555-666666666666",
"players": 120,
"updated_at": "2026-11-12T20:26:37.772Z"
}
}Get outcomes
Get totals for clicks, confirmed deliveries, unsubscribes and sessions over the last hour, day or month. OneSignal's Free plan reports clicks only; the others need a paid plan.
Inputs
- Outcomes
outcomeslist - What to total. Defaults to clicks.One or more of:
os__click.count(Clicks),os__confirmed_delivery.count(Confirmed deliveries),os__unsubscribed.count(Unsubscribes),os__session_duration.sum(Time spent in the app (seconds)),os__session_duration.count(Sessions). - Period
time_rangetext - How far back to count. Defaults to the last day.One of:
1h(Last hour),1d(Last day (default)),1mo(Last month). - Attributed to
attributiontext - Count outcomes that came directly from a message, were only influenced by one, or neither. Defaults to all.One of:
total(Total (default)),direct,influenced,unattributed.
Outputs
countnumber- How many totals there are
outcomeslist- One total per outcome asked for
Example output
{
"count": 1,
"outcomes": [
{
"aggregation": "count",
"id": "os__click",
"value": 14
}
]
}Get template
Get one template with its full content.
Inputs
- Template
template_idtextRequired - The template. Pick one, or give its id from an earlier step.
Outputs
templateobject- The template with its content
Example output
{
"template": {
"channel": "push",
"content": {
"contents": {
"en": "Your order has shipped."
},
"headings": {
"en": "Shipped"
}
},
"created_at": "2026-11-13T18:17:36.771Z",
"id": "6dbb3101-c1e3-4ded-aae6-f74a3b0b61b5",
"name": "Order shipped",
"updated_at": "2026-11-13T18:17:36.779Z"
}
}Get user
Get a user by their external ID or OneSignal ID, with their tags, language, ids and every subscription.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID).
Outputs
external_idtext- The user's external ID, empty if none
identityobject- All of the user's ids, by label
onesignal_idtext- The user's OneSignal ID
propertiesobject- Tags, language, country and time zone
subscriptionslist- The user's subscriptions
Example output
{
"external_id": "customer-1234",
"identity": {
"external_id": "customer-1234",
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed"
},
"onesignal_id": "15e4b24f-6d35-4258-8141-2b0da33169ed",
"properties": {
"country": "US",
"language": "en",
"tags": {
"plan": "pro"
}
},
"subscriptions": [
{
"app_id": "11111111-2222-4333-8444-555555555555",
"app_version": "",
"device_model": "",
"device_os": "",
"enabled": true,
"id": "2c44505f-9b3d-4726-8b92-982807e42f38",
"notification_types": 1,
"sdk": "",
"session_count": 0,
"token": "jo@example.com",
"type": "Email"
}
]
}List notifications
List the app's notifications, newest first, with their delivery counts. Gets one page; to see more, run it again with 'Skip'.
Inputs
- Page size
limitnumber - How many to return, 1 to 50. OneSignal's default is 50.From 1 to 50.
- Skip
offsetnumber - How many to skip, to get a later page. Defaults to none.At least 0.
- Kind
message_typetext - Only messages made in the dashboard, by API, or automated.One of:
0(Dashboard messages),1(API messages),3(Automated messages).
Outputs
countnumber- How many are in this page
limitnumber- The page size used
notificationslist- The notifications
offsetnumber- Where this page starts
total_countnumber- How many there are in all
Example output
{
"count": 1,
"limit": 50,
"notifications": [
{
"app_id": "11111111-2222-4333-8444-555555555555",
"canceled": false,
"completed_at": 1794593770,
"contents": {
"en": "Your order has shipped."
},
"converted": 14,
"data": {},
"email_subject": "",
"errored": 0,
"excluded_segments": [],
"failed": 2,
"headings": {
"en": "Shipped"
},
"id": "b8f1c2de-5a43-4c8e-9a52-1d7b5d0b6c11",
"included_segments": [
"Subscribed Users"
],
"name": "Order shipped",
"platform_delivery_stats": {},
"queued_at": 1794593763,
"received": 98,
"send_after": 1794593763,
"successful": 120,
"template_id": "",
"url": "https://example.com/orders/1"
}
],
"offset": 0,
"total_count": 1
}List segments
List the app's segments (groups of users that messages can be sent to), including OneSignal's built-in ones.
Inputs
None.
Outputs
countnumber- How many are in this page
limitnumber- The page size used
offsetnumber- Where this page starts
segmentslist- The segments
total_countnumber- How many there are in all
Example output
{
"count": 1,
"limit": 300,
"offset": 0,
"segments": [
{
"app_id": "11111111-2222-4333-8444-555555555555",
"created_at": "2026-11-12T20:26:37.729Z",
"description": "",
"id": "f74c400d-af2b-4e27-b1c3-07c2f3a15d88",
"is_active": true,
"name": "Total Subscriptions",
"read_only": false,
"source": "default",
"updated_at": "2026-11-12T20:26:37.729Z"
}
],
"total_count": 1
}List templates
List the app's message templates, optionally only push, email or SMS. Gets one page; to see more, run it again with 'Skip'.
Inputs
- Page size
limitnumber - How many to return, 1 to 50. OneSignal's default is 50.From 1 to 50.
- Skip
offsetnumber - How many to skip, to get a later page. Defaults to none.At least 0.
- Channel
channeltext - Only templates for this channel.One of:
push,email,sms.
Outputs
countnumber- How many are in this page
limitnumber- The page size used
offsetnumber- Where this page starts
templateslist- The templates
total_countnumber- How many there are in all
Example output
{
"count": 1,
"limit": 50,
"offset": 0,
"templates": [
{
"channel": "push",
"created_at": "2026-11-13T18:17:36.771Z",
"id": "6dbb3101-c1e3-4ded-aae6-f74a3b0b61b5",
"name": "Order shipped",
"updated_at": "2026-11-13T18:17:36.779Z"
}
],
"total_count": 1
}Update subscription
Change a subscription's email address or phone number, or turn it on or off.
Inputs
- Subscription ID
subscription_idtextRequired - The subscription's id, from 'Get user' (each entry in its subscriptions) or 'Add subscription'.
- Email or phone number
tokentext - The new address or number. Leave empty to keep it.
- Enabled
enabledtrue/false - Turn it on or off. Leave empty to keep it.
Outputs
enabledtrue/false- The new state, if you gave one
subscription_idtext- The subscription changed
tokentext- The new address or number, if you gave one
updatedtrue/false- Always true once changed
Example output
{
"enabled": true,
"subscription_id": "2c44505f-9b3d-4726-8b92-982807e42f38",
"token": "jo@example.com",
"updated": true
}Update template
Rename a template or change its content. Fields you leave empty stay as they are.
Inputs
- Template
template_idtextRequired - The template. Pick one, or give its id from an earlier step.
- Name
nametext - A new name. Leave empty to keep it.
- Message
messagetext - The text of a push or SMS template.
- Title
headingtext - The title of a push template.
- Subject
subjecttext - The subject line of an email template.
- Body
bodytext - The content of an email template, as HTML.
- Preview text
preheadertext - The short text shown after the subject in an inbox.
- Link
urltext - A web address a push template opens when tapped.
Outputs
templateobject- The template with its content
Example output
{
"template": {
"channel": "push",
"content": {
"contents": {
"en": "Your order has shipped."
},
"headings": {
"en": "Shipped"
}
},
"created_at": "2026-11-13T18:17:36.771Z",
"id": "6dbb3101-c1e3-4ded-aae6-f74a3b0b61b5",
"name": "Order shipped",
"updated_at": "2026-11-13T18:17:36.779Z"
}
}Update user
Change a user's tags, language, country or time zone. Fields you leave empty stay as they are.
Inputs
- User ID
alias_idtextRequired - The user's id, of the kind chosen in 'Find the user by'. An external ID is the id your own system uses for them.
- Find the user by
alias_labeltext - Which id you are giving for the user. Defaults to your own external ID.One of:
external_id(External ID (your own user id) (default)),onesignal_id(OneSignal ID). - Tags
tagsobject - Your own keys and values to keep on the user, for segments and personalised messages. Set a tag to an empty value to remove it.
- Language
languagetext - The user's language code, such as en, fr or pt-BR.
- Country
countrytext - The user's two-letter country code, such as US.
- Time zone
timezone_idtext - The user's time zone, such as America/New_York.
Outputs
alias_idtext- The id the user was found by
propertiesobject- The properties OneSignal now holds
updatedtrue/false- Always true once changed
Example output
{
"alias_id": "customer-1234",
"properties": {
"language": "en",
"tags": {
"plan": "pro"
}
},
"updated": true
}