Server REST API Reference
Log InSign Up

Create an app

post https://api.onesignal.com/apps

Create a new OneSignal app

Overview

Use this API to create a new OneSignal app. This is helpful if you need to create multiple apps and don't want to login to the dashboard to do so. The app can be created in an existing organization or this will create a new organization. The push platform configuration settings for web and mobile can also be populated during app creation using this API.

See Apps & Organizations for more about OneSignal apps and organizations.

How to use this API

Using your Organization API key (available in Organizations > Keys & IDs) you can create a new OneSignal app. The Organization API key is not the same as the REST API key.

The name and organization_id are required.

The name is what you want to call the app. You can get the Organization ID from your OneSignal dashboard or View an app API.

You can include some or all of the parameters for your apps push platform settings in order to set up push immediately, but the email and SMS platform settings must be configured through the OneSignal dashboard. See below for a list of platform specific settings for web, Android, and iOS push notifications.

Web push configuration

Required: site_name, chrome_web_origin, safari_site_origin

Use site_name to set the specific origin URL for your website, and include https://. You should also set the chrome_web_origin and safari_site_origin to the same value and all three must be set in the same request.

Recommended: chrome_web_default_notification_icon, safari_icon_256_256

Use the chrome_web_default_notification_icon and safari_icon_256_256 parameters to set the default icon for web push notifications. These parameters should be set to the URL of a 256x256px png image. See our web push setup guide for more details and examples of where this icon is displayed.

Other : safari_apns_p12, safari_apns_p12_password

You can set your push notification p12 certificate file for Safari Push Notifications using these parameters. The value for safari_apns_p12 should be your p12 certificate converted to base64 encoded format and the value for safari_apns_p12_password should be the password for the same file. For details on how to generate a p12 file, please see our p12 guide .

These parameters are entirely optional and they if not provided we will assign a p12 to your account for you. If using your own p12, you will need to include both the base64 encoded certificate and the password in the same request.

chrome_web_origin

Type string

Description

Chrome (All Browsers except Safari): Required if using web push. The URL to your website. Must use https:// and be the specific origin.

chrome_web_default_notification_icon

Type string

Description

Chrome (All Browsers except Safari): Your default notification icon as a 256x256px .png URL.

site_name

Type string

Description

All Browsers: Recommended if using web push. The Site Name. Requires both chrome_web_origin and safari_site_origin to be set in the same request when setting or updating it.

safari_site_origin

Type string

Description

Safari: Recommended if using web push. The URL to your website. Must use https:// and be the specific origin.

safari_apns_p12

Type string

Description

Safari: Your push notification p12 certificate file for Safari Push Notifications, converted to base64 encoded format. If not provided, then we will assign one.

safari_apns_p12_password

Type string

Description

Safari: Password for the safari_apns_p12 file. Omit if no password.

safari_icon_256_256

Type string

Description

Safari: Your default notification icon as a 256x256px .png URL.

Android mobile push configuration

fcm_v1_service_account_json

Type string

Description

Required if using Android push notifications. Your FCM Service Account JSON file converted to base64 format. See Android: Firebase Credentials for details.

iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

Required if using p8: apns_key_id, apns_team_id, apns_bundle_id, apns_p8

The apns_p8 should be your p8 key file converted to base64 encoded format. you can download your p8 key and retrieve your apns_key_id, apns_team_id, and apns_bundle_id from your Apple developer account by following our p8 configuration guide.

apns_p8 example:

  1. Go to https://www.base64encode.org
  2. Use the "Encode files to Base64 format" and upload the p8 file. Then press the "ENCODE" button and download the file.
    1. This will change the p8 format from: 
      -----BEGIN PRIVATE KEY-----
...
your-4-lines-of-text
...
...
\-----END PRIVATE KEY-----
    2. To this format: LS0tLS1CRUdJTiBQ-some-random-string-of-characters-gS0VZLS0tLS0=
  3. Set that as the value for apns_p8.

Required if using p12: apns_p12, apns_p12_password

The value for safari_apns_p12 should be your p12 certificate converted to base64 encoded format and the value for safari_apns_p12_password should be the password for the same file. For details on how to generate a p12 file, please see our p12 guide .

Other : apns_env, additional_data_is_root_payload

Use apns_env to specify whether this is a production or sandbox environment (leave blank to default to production). Setting additional_data_is_root_payload to true allows iOS push notification data values to be added to the root of the aps payload when sent to the iOS device (omit this value unless you use other push SDKs or not using OneSignal SDK methods to read the payload).

apns_p12

Type string

Description

iOS: Required if using p12 APNS Authentication. Your apple push notification p12 certificate file, converted to Base64 en

apns_p12_password

Type string

Description

iOS: Required if using p12 APNS Authentication. Password for the apns_p12 file. Omit if no password.

apns_env

Type string

Description

iOS: Indicates the APS Environment Entitlement. Omit this field for Production environment (App Store & Test Flight builds). Or set either sandbox or production

apns_key_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_team_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_bundle_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_p8

Type string

Description

iOS: Required if using p8 APNS Authentication. Must be base64 encoded format.

additional_data_is_root_payload

Type boolean

Description

iOS: Allows iOS push notification data values to be added to the root of the aps payload when sent to the iOS device. Only used for special cases. Omit this value unless you use other push SDKs or not using OneSignal SDK methods to read the payload.

Language