Update an existing device's tags in one of your OneSignal apps using the External User ID.

Path Parameters

ParameterTypeDescription
app_idStringRequired: The OneSignal App ID the user record is found under.
external_user_idStringRequired: The External User ID mapped to the device record in OneSignal. Must be actively set on the device to be updated. More details.

Body Parameters

ParameterTypeDescription
tagsHashCustom tags for the device record. Only support string key value pairs. Does not support arrays or other nested objects. 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

🚧

Warning - Android SDK Data Synchronization

The OneSignal Android SDKs leverage cacheing on Data Tags.

Tags added through the Android SDK tagging methods may not update if using the API to change or update the same tag.

For example, if you use 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 since "value1" is cached on the device. You will need to change it to something different through the SDK to be reset.

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 tags

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --data-binary "{
\"tags\":{\"a\":\"1\",\"foo\":\"\"}
}" \
https://onesignal.com/api/v1/apps/:app_id/users/:external_user_id

Result Format - Edit device tags

{"success": true }

🚧

Data Latency

A successful response means our database has received the request. This may take some additional time for the tags to be available on the device.

If using Message Personalization, please allow 30+ seconds before sending your messages.

Language