POST
/
apps
Create an app
curl --request POST \
  --url https://api.onesignal.com/apps \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "name": "NAME_OF_NEW_APP",
  "organization_id": "YOUR_ORG_ID",
  "chrome_web_origin": "<string>",
  "site_name": "SITE_NAME",
  "safari_site_origin": "<string>",
  "chrome_web_default_notification_icon": "<string>",
  "safari_icon_256_256": "<string>",
  "safari_apns_p12": "<string>",
  "safari_apns_p12_password": "<string>",
  "fcm_v1_service_account_json": "<string>",
  "apns_p8": "<string>",
  "apns_env": "<string>",
  "apns_key_id": "<string>",
  "apns_team_id": "<string>",
  "apns_bundle_id": "<string>",
  "apns_p12": "<string>",
  "apns_p12_password": "<string>",
  "additional_data_is_root_payload": false
}'
{
  "id": "<string>",
  "name": "<string>",
  "players": 123,
  "messageable_players": 123,
  "created_at": "<string>",
  "updated_at": "<string>",
  "organization_id": "<string>"
}

​
Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though Email and SMS must be set up manually via the OneSignal Dashboard.

For an overview of how apps and organizations work in OneSignal, see Apps & Organizations.

​
How to use this API

Use your Organization API Key, to authenticate. This key is different from the standard REST API key.

The Organization API key must be assocated with the organization_id in the request body.

​
Web push configuration

The following three parameters are required for web push setup:

  • site_name
  • chrome_web_origin
  • safari_site_origin

Recommended parameters:

  • chrome_web_default_notification_icon: URL of a 256x256px PNG for Chrome.
  • safari_icon_256_256: URL of a 256x256px PNG for Safari.

Optional parameters : Use the following parameters if you have your own p12 certificate for Safari Push Notifications. If omitted, we will assign one to your app for you.

  • safari_apns_p12: Base64 encoded p12 certificate for Safari Push Notifications.
  • safari_apns_p12_password: Password for the safari_apns_p12 file if set.

If you use your own p12 certificate, you must update it every year.

If you need help Base64 encoding your p12 certificate, you can use the following site: https://www.base64encode.org

​
Android mobile push configuration

The following parameter is required for Android push notifications. See Android: Firebase Credentials.

  • fcm_v1_service_account_json

If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: https://www.base64encode.org

​
iOS mobile push configuration

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

If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: https://www.base64encode.org

The following parameters are required if using p8 Token-based connection to APNS:

  • apns_key_id
  • apns_team_id
  • apns_bundle_id
  • apns_p8

The following parameters are required if using p12 APNS Authentication:

  • apns_p12
  • apns_p12_password

Optional parameters :

  • additional_data_as_root_payload: If set to true, the data paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our OSNotification payload additionalData property.

Headers

​
Content-Type
string
default:application/json
required
​
Authorization
string
default:Key YOUR_ORGANIZATION_API_KEY
required

Your Organization API key with prefix Key. See Keys & IDs.

Body

application/json
​
name
string
default:NAME_OF_NEW_APP
required

An internal name you set to help organize and track Apps. Maximum 128 characters.

​
organization_id
string
default:YOUR_ORG_ID
required

The Organization ID that the app will be associated with.

​
chrome_web_origin
string

The HTTPS origin URL for your website. Required for web push notifications.

​
site_name
string
default:SITE_NAME

The name of your website. Used for web push notification titles when omitted from the notification payload. Required for web push notifications.

​
safari_site_origin
string

The HTTPS origin URL for your website. Required for web push notifications for Safari and should be the same as chrome_web_origin.

​
chrome_web_default_notification_icon
string

The full https URL to your default icon resource. The icon should be a 256x256px PNG.

​
safari_icon_256_256
string

The full https URL to your default icon resource. The icon should be a 256x256px PNG.

​
safari_apns_p12
string

A Base64 encoded p12 certificate for Safari Push Notifications. If omitted, we will assign one to your app for you.

​
safari_apns_p12_password
string

The password for the safari_apns_p12 file if applicable.

​
fcm_v1_service_account_json
string

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

​
apns_p8
string

A Base64 encoded p8 file for iOS mobile Push Notifications. Omit if using apns_p12. See p8 Token-based connection to APNS.

​
apns_env
string

The APS Environment Entitlement to specify whether this is a production or development environment. Defaults to production. Use with apns_p8.

​
apns_key_id
string

The APNS Key ID. Use with apns_p8. See p8 Token-based connection to APNS.

​
apns_team_id
string

The APNS Team ID. Use with apns_p8. See p8 Token-based connection to APNS.

​
apns_bundle_id
string

The Bundle ID for your app. Use with apns_p8. See p8 Token-based connection to APNS.

​
apns_p12
string

A Base64 encoded p12 certificate for iOS mobile push notifications. Omit if using apns_p8. See p12 APNS Authentication.

​
apns_p12_password
string

The password for the apns_p12 file if applicable.

​
additional_data_is_root_payload
boolean
default:false

If set to true, the data paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our OSNotification payload additionalData property.

Response

200 - application/json

200

​
id
string

The OneSignal App ID in UUID v4 format.

​
name
string

An internal name you set to help organize and track Apps. Maximum 128 characters.

​
players
integer

The total number of Subscriptions in the app.

​
messageable_players
integer

The number of Subscriptions eligible to receive messages in the app.

​
created_at
string

The date and time the app was created.

​
updated_at
string

The date and time the app was last updated.

​
organization_id
string

The Organization ID in which the app was created.