# OneSignal REST API

The OneSignal REST API enables developers to programmatically send push notifications, emails, and SMS, manage users and subscriptions, and configure apps.

- **Category:** notifications
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 15
- **Triggers:** 0
- **Slug:** `ONESIGNAL_REST_API`
- **Version:** 20260223_00

## Tools

### Begin Live Activity

**Slug:** `ONESIGNAL_REST_API_BEGIN_LIVE_ACTIVITY`

Tool to start a Live Activity on OneSignal. Use when you need to initiate a Live Activity session with a push token and subscription ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | The OneSignal App ID for your app. Available in Keys & IDs. |
| `push_token` | string | Yes | The device's push token for Live Activities (64-character hexadecimal string) |
| `activity_id` | string | Yes | Live Activity record ID |
| `subscription_id` | string | Yes | The OneSignal subscription ID associated with the device |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Notification

**Slug:** `ONESIGNAL_REST_API_CREATE_NOTIFICATION`

Tool to create and send a OneSignal push notification. Use when you have your message and target audience ready to dispatch notifications.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | URL to open when the notification is tapped |
| `data` | object | No | Custom key/value data payload |
| `app_id` | string | Yes | Your OneSignal App ID |
| `buttons` | array | No | Action buttons; see OneSignal docs for fields (id, text, icon, url) |
| `filters` | array | No | Advanced audience filters; see OneSignal docs for syntax |
| `contents` | object | Yes | Notification message per language |
| `headings` | object | No | Notification title per language |
| `subtitle` | object | No | Notification subtitle per language |
| `ios_sound` | string | No | Custom iOS sound file |
| `large_icon` | string | No | URL for Android large icon |
| `send_after` | string | No | Schedule delivery time in ISO 8601 format (e.g., '2023-09-01T12:00:00Z') |
| `big_picture` | string | No | URL for Android big picture |
| `extra_params` | object | No | Additional OneSignal parameters not explicitly modeled above |
| `android_sound` | string | No | Custom Android sound file |
| `delayed_option` | string ("timezone" | "last-active") | No | Delay delivery based on 'timezone' or 'last-active' |
| `ios_attachments` | object | No | iOS media attachments mapping identifiers to URLs |
| `included_segments` | array | No | Predefined audience segments (e.g., ['All']) |
| `android_channel_id` | string | No | Android channel ID to post notification to |
| `include_player_ids` | array | No | Specific device/player IDs to send the notification to |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Template

**Slug:** `ONESIGNAL_REST_API_CREATE_TEMPLATE`

Tool to create reusable message templates for push, email, and SMS channels. Use when you need to create a template that can be accessed through both the dashboard and API using a template_id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | Associated URL for the notification |
| `isWP` | boolean | No | Platform targeting flag for Windows Phone (defaults to true) |
| `name` | string | Yes | Internal name for organizing and tracking templates (maximum 128 characters) |
| `isAdm` | boolean | No | Platform targeting flag for Amazon (defaults to true) |
| `isIos` | boolean | No | Platform targeting flag for iOS (defaults to true) |
| `isSMS` | boolean | No | Required to be set true for SMS templates |
| `app_id` | string | Yes | Your OneSignal App ID |
| `isEdge` | boolean | No | Platform targeting flag for Microsoft Edge (defaults to true) |
| `isEmail` | boolean | No | Required to be set true for email templates |
| `contents` | object | No | The main message body with language-specific values (e.g., {'en': 'Hello!'}). Applies to push and SMS templates. Supports message personalization. |
| `headings` | object | No | Language-specific heading values for push notifications |
| `isChrome` | boolean | No | Platform targeting flag for Chrome Apps (defaults to true) |
| `isMacOSX` | boolean | No | Platform targeting flag for macOS (defaults to true) |
| `isSafari` | boolean | No | Platform targeting flag for Safari (defaults to true) |
| `isWP_WNS` | boolean | No | Platform targeting flag for Windows Push Notification Services (defaults to true) |
| `isAndroid` | boolean | No | Platform targeting flag for Android (defaults to true) |
| `isFirefox` | boolean | No | Platform targeting flag for Firefox (defaults to true) |
| `email_body` | string | No | The body of the email in HTML format (required when creating email templates). Supports message personalization. |
| `isChromeWeb` | boolean | No | Platform targeting flag for Chrome Web Push (defaults to true) |
| `email_subject` | string | No | The subject of the email (required when creating email templates). Supports message personalization. |
| `dynamic_content` | object | No | Enables programmatic personalization without CSV uploads. Structure supports nested key-value campaign variations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create User

**Slug:** `ONESIGNAL_REST_API_CREATE_USER`

Tool to create a OneSignal user with optional subscriptions and aliases. Aliases provided in the payload will be used to look up an existing user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Your OneSignal App ID |
| `identity` | object | No | Identity object for user identification. Aliases provided will be used to look up an existing user. |
| `properties` | object | No | User properties including location, activity, and custom data. |
| `subscriptions` | array | No | List of subscriptions (devices/channels) owned by the user |
| `subscription_options` | object | No | Options for subscription management. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Alias

**Slug:** `ONESIGNAL_REST_API_DELETE_ALIAS`

Tool to delete an alias by alias label from a OneSignal user. Use when you need to remove a specific alias identity from a user's profile.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | The OneSignal App ID |
| `alias_id` | string | Yes | The value of the alias to identify the user |
| `alias_label` | string | Yes | The alias label to identify the user (e.g., 'external_id', 'email') |
| `alias_label_to_delete` | string | Yes | The alias label to delete from the user's identity (e.g., 'email', 'phone_number') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Device

**Slug:** `ONESIGNAL_REST_API_DELETE_DEVICE`

Tool to delete a device (player) from a OneSignal app. Use when you need to remove a specific device by its player ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | The OneSignal App ID |
| `player_id` | string | Yes | The OneSignal Player (Device) ID to delete |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch User Identity

**Slug:** `ONESIGNAL_REST_API_FETCH_USER_IDENTITY`

Tool to retrieve all aliases for a user identified by a specific alias. Use when you need to fetch the complete identity mapping for a OneSignal user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Your OneSignal App ID. |
| `alias_id` | string | Yes | The alias value/ID to identify the user (e.g., 'test-user-123', 'user@example.com'). |
| `alias_label` | string | Yes | The alias label to identify the user (e.g., 'external_id', 'email', 'phone_number'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Eligible In-App Messages

**Slug:** `ONESIGNAL_REST_API_GET_ELIGIBLE_IAMS`

Tool to retrieve the manifest of In-App Messages that a subscription is eligible to display. Use when you need to fetch eligible IAMs for a specific subscription.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Unique identifier for the OneSignal app. |
| `subscription_id` | string | Yes | Unique identifier for the subscription (device/player). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Device

**Slug:** `ONESIGNAL_REST_API_UPDATE_DEVICE`

Tool to update properties of an existing device. Use when you need to modify device attributes after registration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | object | No | Custom tags for the device |
| `ad_id` | string | No | Advertising ID |
| `app_id` | string | Yes | Your OneSignal App ID |
| `country` | string | No | Country code, e.g., 'US' |
| `language` | string | No | Language code, e.g., 'en' |
| `latitude` | number | No | Latitude coordinate |
| `playtime` | integer | No | Total playtime in seconds |
| `timezone` | integer | No | Timezone offset in seconds from UTC |
| `device_os` | string | No | Operating system version |
| `longitude` | number | No | Longitude coordinate |
| `player_id` | string | Yes | Unique OneSignal device/player ID |
| `test_type` | integer | No | 1 for development, 2 for ad-hoc |
| `created_at` | integer | No | Unix timestamp when the device was created |
| `identifier` | string | No | Push token, email address, or external user ID |
| `badge_count` | integer | No | iOS badge count |
| `device_type` | integer | No | Device type. See OneSignal docs for list |
| `last_active` | integer | No | Unix timestamp when the device was last active |
| `amount_spent` | string | No | Amount the user has spent |
| `device_model` | string | No | Device model |
| `game_version` | string | No | Version of the app/game |
| `sms_auth_hash` | string | No | SMS authentication hash |
| `email_auth_hash` | string | No | Email authentication hash |
| `external_user_id` | string | No | External user ID |
| `custom_attributes` | object | No | Additional custom attributes |
| `notification_types` | integer | No | Notification permission state |
| `external_user_id_auth_hash` | string | No | Auth hash for external_user_id |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Subscription

**Slug:** `ONESIGNAL_REST_API_UPDATE_SUBSCRIPTION`

Tool to update an existing subscription's properties. Use when you need to modify subscription attributes like token, enabled status, or device information.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Your OneSignal App ID. |
| `subscription` | object | Yes | The subscription properties to update. |
| `subscription_id` | string | Yes | The unique ID of the subscription to update. |
| `retain_previous_owner` | boolean | No | Whether to retain the previous owner when updating the subscription. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### View OneSignal App

**Slug:** `ONESIGNAL_REST_API_VIEW_AN_APP`

Tool to retrieve metadata for a single OneSignal app. Use when you need to fetch app details by its ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Unique identifier for the OneSignal app. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### View Device

**Slug:** `ONESIGNAL_REST_API_VIEW_DEVICE`

Tool to retrieve details of a specific device (player). Use when you have a OneSignal player_id and need current device info.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string | Yes | Your OneSignal App ID. |
| `player_id` | string | Yes | Unique ID of the device (player) to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### View Devices

**Slug:** `ONESIGNAL_REST_API_VIEW_DEVICES`

Tool to retrieve a paginated list of devices (players) for a OneSignal app. Use when you need to list or audit all registered devices for a given app.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of devices to return (1-300). Defaults to 300. |
| `app_id` | string | Yes | Your OneSignal App ID. |
| `offset` | integer | No | Pagination offset. Defaults to 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### View Notifications

**Slug:** `ONESIGNAL_REST_API_VIEW_NOTIFICATIONS`

Tool to retrieve details of multiple notifications. Use when you need to list notifications for a specific app.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of notifications to return (1-300). Defaults to 50. |
| `app_id` | string | Yes | Your OneSignal App ID. |
| `offset` | integer | No | Result offset for pagination. Defaults to 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### View Segments

**Slug:** `ONESIGNAL_REST_API_VIEW_SEGMENTS`

Tool to view segments for a OneSignal app. Use when you need to list all segments associated with an app.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of segments to return (1-300). Default is 50. |
| `app_id` | string | Yes | OneSignal App ID to list segments for |
| `offset` | integer | No | Zero-based offset for pagination. Results sorted by creation time. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |