Hey! These docs are for version 7.0, which is no longer officially supported. Click here for the latest version, 9.0!

Register a new device to one of your OneSignal apps


Not Recommended, use the SDK instead

This API endpoint is designed to be used from our open source Mobile and Web Push SDKs. It is not designed for developers to use it directly. See
Onboarding With OneSignal.

If you use this method instead of our SDKs, many OneSignal features such as conversion tracking, timezone tracking, language detection, and rich-push won't work out of the box. It will also make it harder to identify possible setup issues.

This method is used to register a new device with OneSignal.

If a device is already registered with the specified identifier, then this will update the existing device record instead of creating a new one.

The returned ID is for the OneSignal Device Channel Record. If you set device_type = 11 the returned ID is for the Email Channel associated with the device. device_type = 14 is the SMS Channel. All other device_type correspond to the Push Channel. It is recommended to include an external_user_id to associate all Device Channel Records with your own User ID.



Must set test_type to 1 when building your iOS app as development. Omit this field in your production app builds.

Body Parameters - Add a device

app_idStringRequired Your OneSignal App Id found in Keys & IDs.
device_typeIntRequired The device's platform:

0 = iOS
1 = Android
2 = Amazon
3 = WindowsPhone (MPNS)
4 = Chrome Apps / Extensions
5 = Chrome Web Push
6 = Windows (WNS)
7 = Safari
8 = Firefox
9 = MacOS
10 = Alexa
11 = Email
13 = For Huawei App Gallery Builds SDK Setup. Not for Huawei Devices using FCM
14 = SMS
identifier_auth_hash StringOnly required if you have enabled Identity Verification and device_type is 11 (Email) or 14 SMS (coming soon).
identifierStringRecommended: For Push Notifications, this is the Push Token Identifier from Google or Apple. For Apple Push identifiers, you must strip all non alphanumeric characters.
iOS: 7abcd558f29d0b1f048083e2834ad8ea4b3d87d8ad9c088b33c132706ff445f0


Email Addresses: set the full email address [email protected] and make sure to set device_type to 11.

Phone Numbers: set the E.164 format and make sure to set device_type to 14.
test_typeIntThis is used in deciding whether to use your iOS Sandbox or Production push certificate when sending a push when both have been uploaded. Set to the iOS provisioning profile that was used to build your app.
1 = Development
2 = Ad-Hoc
Omit this field for App Store builds.
languageStringRecommended Language code. Typically lower case two letters, except for Chinese where it must be one of zh-Hans or zh-Hant. Example: en
timezoneIntRecommended Number of seconds away from UTC. Example: -28800
game_versionStringRecommended Version of your app. Example: 1.1
device_modelStringRecommended Device make and model. Example: iPhone5,1
device_osStringRecommended Device operating system version. Example: 7.0.4
ad_idStringThe ad id for the device's platform:
Android = Advertising Id

iOS = identifierForVendor

WP8.1 = AdvertisingId
sdkStringRecommended Name and version of the plugin that's calling this API method (if any)
session_countIntNumber of times the user has played the game, defaults to 1
tagsHashCustom tags for the player. Only support string key value pairs. Does not support arrays or other nested objects. Example: {"foo":"bar","this":"that"}
amount_spentStringAmount the user has spent in USD, up to two decimal places
created_atIntUnix timestamp in seconds indicating date and time when the device downloaded the app or subscribed to the website.
playtimeIntSeconds player was running your app.
last_activeIntUnix timestamp in seconds indicating date and time when the device last used the app or website.
notification_typesInt1 = subscribed
-2 = unsubscribed

iOS - These values are set each time the user opens the app from the SDK. Use the SDK function set Subscription instead.

Android - You may set this but you can no longer use the SDK method setSubscription later in your app as it will create synchronization issues.
longDoubleLongitude of the device, used for geotagging to segment on.
latDoubleLatitude of the device, used for geotagging to segment on.
countryStringCountry code in the ISO 3166-1 Alpha 2 format
external_user_idStringA custom user ID
external_user_id_auth_hashStringOnly required if you have enabled Identity Verification and device_type is NOT 11 email.

Example Code - Add a device

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{\"app_id\" : \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",
\"device_model\":\"iPhone 8,2\",
\"tags\":{\"a\":\"1\",\"foo\":\"bar\"}}" \
$fields = array( 
'app_id' => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
'identifier' => "ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566", 
'language' => "en", 
'timezone' => "-28800", 
'game_version' => "1.0", 
'device_os' => "9.1.3", 
'device_type' => "0", 
'device_model' => "iPhone 8,2", 
'tags' => array("foo" => "bar") 

$fields = json_encode($fields); 
print("\nJSON sent:\n"); 

$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, "https://onesignal.com/api/v1/players"); 
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); 
curl_setopt($ch, CURLOPT_HEADER, FALSE); 
curl_setopt($ch, CURLOPT_POST, TRUE); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); 

$response = curl_exec($ch); 

$return["allresponses"] = $response; 
$return = json_encode( $return); 

print("\n\nJSON received:\n"); 


Result Format - Add a device

{"success": true, "id": "ffffb794-ba37-11e3-8077-031d62f86ebf" }