OneSignal

App · 18 actions

Manage OneSignal users, subscriptions, segments and message templates, and read notifications, clicks and deliveries.

Actions

ActionWhat it does
Add subscriptionAdd an email address or phone number to an existing user so you can message them there.
Add user aliasGive a user another id of your own, such as a CRM id, so you can find them by it later.
Create or update userCreate a user by your own external ID, with tags and an email address or phone number to message.
Create templateCreate a reusable push, email or SMS message template.
Delete subscriptionDelete one subscription.
Delete templateDelete a template.
Delete userDelete a user and all of their subscriptions.
Delete user aliasRemove one of a user's extra ids.
Get appGet the connected OneSignal app: its name, how many users can receive messages, and which channels (push, email, SMS) are on.
Get outcomesGet totals for clicks, confirmed deliveries, unsubscribes and sessions over the last hour, day or month.
Get templateGet one template with its full content.
Get userGet a user by their external ID or OneSignal ID, with their tags, language, ids and every subscription.
List notificationsList the app's notifications, newest first, with their delivery counts.
List segmentsList the app's segments (groups of users that messages can be sent to), including OneSignal's built-in ones.
List templatesList the app's message templates, optionally only push, email or SMS.
Update subscriptionChange a subscription's email address or phone number, or turn it on or off.
Update templateRename a template or change its content.
Update userChange 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 IDalias_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.
Typesubscription_typetextRequired
Whether this is an email address or a phone number.One of: Email (Email address), SMS (Phone number (SMS)).
Email or phone numbertokentextRequired
The email address, or the phone number with its country code, like +15555555555.
Find the user byalias_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).
Enabledenabledtrue/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 IDalias_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 namenew_labeltextRequired
What kind of id this is, such as crm_id.
Alias valuenew_idtextRequired
The id itself.
Find the user byalias_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 IDexternal_idtextRequired
The id your own system uses for this user.
Email addressemailtext
Adds an email subscription so you can email them.
Phone numberphone_numbertext
Adds an SMS subscription. Include the country code, like +15555555555.
Tagstagsobject
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.
Languagelanguagetext
The user's language code, such as en, fr or pt-BR.
Countrycountrytext
The user's two-letter country code, such as US.
Time zonetimezone_idtext
The user's time zone, such as America/New_York.
Other IDsaliasesobject
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

NamenametextRequired
The template's name, shown in OneSignal.
Channelchanneltext
What the template sends. Defaults to push.One of: push, email, sms.
Messagemessagetext
The text of a push or SMS template.
Titleheadingtext
The title of a push template.
Subjectsubjecttext
The subject line of an email template.
Bodybodytext
The content of an email template, as HTML.
Preview textpreheadertext
The short text shown after the subject in an inbox.
Linkurltext
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 IDsubscription_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

Templatetemplate_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 IDalias_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 byalias_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 IDalias_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 namelabel_to_removetextRequired
The kind of id to remove, such as crm_id.
Find the user byalias_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

Outcomesoutcomeslist
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).
Periodtime_rangetext
How far back to count. Defaults to the last day.One of: 1h (Last hour), 1d (Last day (default)), 1mo (Last month).
Attributed toattributiontext
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

Templatetemplate_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 IDalias_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 byalias_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 sizelimitnumber
How many to return, 1 to 50. OneSignal's default is 50.From 1 to 50.
Skipoffsetnumber
How many to skip, to get a later page. Defaults to none.At least 0.
Kindmessage_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 sizelimitnumber
How many to return, 1 to 50. OneSignal's default is 50.From 1 to 50.
Skipoffsetnumber
How many to skip, to get a later page. Defaults to none.At least 0.
Channelchanneltext
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 IDsubscription_idtextRequired
The subscription's id, from 'Get user' (each entry in its subscriptions) or 'Add subscription'.
Email or phone numbertokentext
The new address or number. Leave empty to keep it.
Enabledenabledtrue/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

Templatetemplate_idtextRequired
The template. Pick one, or give its id from an earlier step.
Namenametext
A new name. Leave empty to keep it.
Messagemessagetext
The text of a push or SMS template.
Titleheadingtext
The title of a push template.
Subjectsubjecttext
The subject line of an email template.
Bodybodytext
The content of an email template, as HTML.
Preview textpreheadertext
The short text shown after the subject in an inbox.
Linkurltext
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 IDalias_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 byalias_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).
Tagstagsobject
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.
Languagelanguagetext
The user's language code, such as en, fr or pt-BR.
Countrycountrytext
The user's two-letter country code, such as US.
Time zonetimezone_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
}

On this page