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.

🚧

iOS

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

Parameter

Type

Description

app_id

String

Required Your OneSignal App Id found in Keys & IDs.

device_type

Int

Required 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

String

Only required if you have enabled Identity Verification and device_type is 11 (Email) or 14 SMS (coming soon).

identifier

String

Recommended: For Push Notifications, this is the Push Token Identifier from Google or Apple. For Apple Push identifiers, you must strip all non alphanumeric characters.
Examples:
iOS: 7abcd558f29d0b1f048083e2834ad8ea4b3d87d8ad9c088b33c132706ff445f0

Android:
APA91bHbYHk7aq-Uam_2pyJ2qbZvqllyyh2wjfPRaw5gLEX2SUlQBRvOc6sck1sa7H7nGeLNlDco8lXj83HWWwzV...

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_type

Int

This 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.

language

String

Recommended Language code. Typically lower case two letters, except for Chinese where it must be one of zh-Hans or zh-Hant. Example: en

timezone

Int

Recommended Number of seconds away from UTC. Example: -28800

game_version

String

Recommended Version of your app. Example: 1.1

device_model

String

Recommended Device make and model. Example: iPhone5,1

device_os

String

Recommended Device operating system version. Example: 7.0.4

ad_id

String

The ad id for the device's platform:
Android = Advertising Id

iOS = identifierForVendor

WP8.1 = AdvertisingId

sdk

String

Recommended Name and version of the plugin that's calling this API method (if any)

session_count

Int

Number of times the user has played the game, defaults to 1

tags

Hash

Custom tags for the player. Only support string key value pairs. Does not support arrays or other nested objects. Example: {"foo":"bar","this":"that"}

amount_spent

String

Amount the user has spent in USD, up to two decimal places

created_at

Int

Unix timestamp in seconds indicating date and time when the device downloaded the app or subscribed to the website.

playtime

Int

Seconds player was running your app.

last_active

Int

Unix timestamp in seconds indicating date and time when the device last used the app or website.

notification_types

Int

1 = 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.

long

Double

Longitude of the device, used for geotagging to segment on.

lat

Double

Latitude of the device, used for geotagging to segment on.

country

String

Country code in the ISO 3166-1 Alpha 2 format

external_user_id

String

A custom user ID

external_user_id_auth_hash

String

Only 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\",
\"identifier\":\"ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566\",
\"language\":\"en\",
\"timezone\":-28800,
\"game_version\":\"1.0\",
\"device_os\":\"7.0.4\",
\"device_type\":0,
\"device_model\":\"iPhone 8,2\",
\"tags\":{\"a\":\"1\",\"foo\":\"bar\"}}" \
     https://onesignal.com/api/v1/players
<?PHP
$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"); 
print($fields); 

$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_RETURNTRANSFER, TRUE); 
curl_setopt($ch, CURLOPT_HEADER, FALSE); 
curl_setopt($ch, CURLOPT_POST, TRUE); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); 

$response = curl_exec($ch); 
curl_close($ch); 

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

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

?>

Result Format - Add a device

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