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

Edit device

put https://onesignal.com/api/v1/players/:id

Update an existing device in one of your OneSignal apps

Path Parameters

ParameterTypeDescription
idStringRequired The device's OneSignal ID

Body Parameters

ParameterTypeDescription
app_idStringRequired Your OneSignal App Id found in Keys & IDs
identifierStringPush notification identifier from Google or Apple. For Apple push identifiers, you must strip all non alphanumeric characters. Example: ce777617da7f548fe7a9ab6febb56
languageStringLanguage code. Typically lower case two letters, except for Chinese where it must be one of zh-Hans or zh-Hant. Example: en
timezoneIntNumber of seconds away from UTC. Example: -28800
game_versionStringVersion of your app. Example: 1.1
device_modelStringDevice make and model. Example: iPhone5,1
device_osStringDevice operating system version. Example: 7.0.4
ad_idStringThe ad id for the device's platform:
Android = Advertising Id
iOS = identifierForVendor
WP8.0 = DeviceUniqueId
WP8.1 = AdvertisingId
sdkStringName and version of the sdk/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 and integer key value pairs. Does not support arrays or other nested objects. Setting a tag value to null or an empty string will remove the tag. Example: {"foo":"bar","this":"that"}

Limitations:
- 100 tags per call
- Android SDK users: tags cannot be removed or changed via API if set through SDK sendTag methods.

Recommended to only tag devices with 1 kilobyte of data

Please consider using your own Database to save more than 1 kilobyte of data. See: Internal Database & CRM
amount_spentStringAmount the user has spent in USD, up to two decimal places
created_atIntUnixtime when the player joined the game
playtimeIntSeconds player was running your app.
badge_countIntCurrent iOS badge count displayed on the app icon

NOTE: Not supported for apps created after June 2018, since badge count for apps created after this date are handled on the client.
last_activeIntUnixtime when the player was last active
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.
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.
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

🚧

Warning - Android SDK Data Synchronization

The OneSignal Android SDKs leverage cacheing on external_user_id and Data Tags.

external_user_id or tags added client-side through the Android SDK are cached. They can be changed server-side, but will not be changed back to the original client-side values if tried to set again through the SDK.

For example, if calling the SDK method sendTag("key", "value1") then update the tag value to "value2" with this API endpoint. You will not be able to set the value back to "value1" through the SDK. You will need to set a new value client side or reset the value server side.

Recommendations if using this Endpoint on Android Mobile Apps:
1 - Do not use the same tag keys for SDK and API updates
2 - If you want to use the same key for both SDK and API updates, call the SDK getTags method first to update the device's tags.

This is only applicable on the Android Mobile App SDKs.

📘

Deleting Tags

To delete a tag, include its key and set its value to blank. Omitting a key/value will not delete it.

For example, if I wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the tags JSON would look like the following:

"tags": {
           "rank": "",
           "category": "",
           "class": "my_new_value"
        }

Example Code - Edit device

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "{\"app_id\" : \"APP_ID\", \
\"language\":\"es\",\
\"timezone\":-28800,\
\"game_version\":\"1.0\",\
\"device_os\":\"7.0.4\",\
\"device_type\":0,\
\"device_model\":\"iPhone\",\
\"tags\":{\"a\":\"1\",\"foo\":\"\"}}" \
     https://onesignal.com/api/v1/players/PLAYER_ID

<?PHP
$playerID = '8dee0e23-410d-4a9a-b8ce-bfe4c5257ccc';
$fields = array( 
'app_id' => '02b297e7-abb5-4e7e-9c2a-9ce7e2c82ff5', 
'tags' => array('OneSignal_Example_Tag' => 'YES')
); 
$fields = json_encode($fields); 

$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, 'https://onesignal.com/api/v1/players/'.$playerID); 
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_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); 
$response = curl_exec($ch); 
curl_close($ch); 

$resultData = json_decode($response, true);
echo $resultData;
?>

Result Format - Edit device

{"success": true }
Language