Update an existing user by its alias
Compatibility with Pre-User Model SDKs and APIs
If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or lower, Web SDKs version 15 or lower), we recommend thorough testing of this endpoint before switching to the new User Model. Discrepancies may occur where the External ID set through the SDK and the External ID set through the API do not generate matching OneSignal IDs.
To ensure a smooth transition, consider the following options:
- Update to the User Model SDKs: Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the User Model Migration Guide.
- Continue Using Pre-User Model APIs: If you are not ready to migrate, continue using the existing APIs for Adding a Device, Editing Tags with External User ID, and Editing a Device until the SDK migration is complete.
Overview
This endpoint allows you to modify user profile data, add or update aliases, and manage subscriptions for the user identified by a given alias.
How to Use this API
To identify and update a user using their OneSignal ID, use onesignal_id
as the alias label and the user’s ID as the alias ID.
What Can Be Updated?
- User Profile: Tags, language preferences, geographic information, and other properties.
- Aliases: Custom identifiers such as
facebook_id
or any other custom alias can be added or updated (except for the OneSignal ID alias, which is read-only). - Subscriptions: Create or transfer new subscriptions to the user.
Note: Authentication is required when using any alias other than the OneSignal ID.
Examples
Update user via OneSignal ID
curl -X "PATCH" "https://api.onesignal.com/apps/<APP_ID>/users/by/onesignal_id/<ONESIGNAL_ID>" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"deltas": {
"session_time": 0,
"session_count": 1,
"purchases": [
{
"amount": "33.33",
"iso": "USD",
"count": 3,
"sku": "item"
},
{
"amount": ".01",
"iso": "USD",
"count": 1,
"sku": "item-1"
}
]
},
"properties": {
"tags": {
"existingTag": "New value"
},
"purchases": [
{
"count": 3,
"iso": "USD",
"sku": "Item1"
}
]
}
}'
Update user via Alias (requires auth)
curl -X "PATCH" "https://api.onesignal.com/apps/<APP_ID>/users/by/onesignal_id/<ONESIGNAL_ID>" \
-H 'Content-Type: application/json; charset=utf-8' \
-u '<REST_API_KEY>:' \
-d $'{
"deltas": {
"session_time": 0,
"session_count": 1,
"purchases": [
{
"amount": "33.33",
"iso": "USD",
"count": 3,
"sku": "item"
},
{
"amount": ".01",
"iso": "USD",
"count": 1,
"sku": "item-1"
}
]
},
"properties": {
"tags": {
"existingTag": "New value"
},
"purchases": [
{
"count": 3,
"iso": "USD",
"sku": "Item1"
}
]
}
}'
Path Parameters
alias_label
alias_label
Description
The name of the alias to use to fetch a user. All users include a special OneSignal ID alias named onesignal_id
.
Guidance
- We recommend fetching users via your identifier using the External ID alias:
external_id
. - Refer to our guide on Aliases & External ID for further details.
alias_id
alias_id
Description
The specific identifier for a given Alias to identify the user.
Guidance
- Refer to our guide on Aliases & External ID for further details.
Body Parameters
properties
properties
Type object
See UserProperties for details.
Description
Lets you specify user data, including tags and activity.
Guidance
- User data helps you personalize your user experience, track user behavior, and improve engagement through targeted push notifications, emails, and text messages.
Example
{
"tags": {
"foo": "bar",
"this": "that"
},
"language": "en",
"timezone_id": "America/Los_Angeles",
"lat": 37.7749,
"long": -122.4194,
"country": "US",
"first_active": 1589788800,
"last_active": 1589788800,
"purchases": 0,
"ip": 3232235777
}
deltas
deltas
Type object
See DeltasObject for details.
Description
User properties that change frequently and generally only increment.
Request Object Definitions
UserProperties
UserProperties
The UserProfile
object represents a user's profile data, including tags, user activity, and other relevant properties.
tags
tags
Type object
Description
Custom user events or properties are represented as key-value pairs. These tags can be used for various purposes, such as segmentation, personalization, and tracking user behavior. For more details, see Data Tags.
Guidance
- Only string key-value pairs are supported; arrays and other nested objects are not.
- Use tags to specify attributes or events related to a user, enabling targeted engagement and personalized experiences.
language
language
Type string
Description
Language Abbreviation in ISO 639-1 format.
Guidance
- Specify the user's preferred language to tailor content and notifications to their linguistic preferences; the default is
en
. - Must be lowercase.
timezone_id
timezone_id
Type string
Description
Timezone ID based on the tz database "TZ identifier".
Guidance
- Use the timezone ID to schedule notifications and other time-sensitive communications per the user's local time.
- The default is
America/Los_Angeles
lat
lat
Type number
Description
The user's current latitude.
Guidance
- Latitude data can be used for location-based targeting and personalized content delivery.
- Acceptable values range between -90 to 90.
long
long
Type number
Description
The user's current longitude.
Guidance
- Longitude data, when paired with latitude, enables precise geographic targeting.
- Acceptable values range between -180 to 180.
country
country
Type string
Description
Country code in ISO 3166-1 Alpha 2 format.
Guidance
- Use the country code to localize content.
- Must be upper-case.
first_active
first_active
Type number
Description
The time the user was first created. Represented as a Unix timestamp in seconds.
Guidance
- Enables you to calculate the duration of a user's engagement from the first interaction.
last_active
last_active
Type number
Description
The most recent time the user was active in your app. Represented as a Unix timestamp in seconds.
Guidance
- Use this field to gauge user engagement and inactivity to and trigger re-engagement campaigns.
purchases
purchases
Type number
Description
The User's in-app purchase information.
Guidance
- Recommended for mobile apps. Consider using Data Tags to segment users based on purchase behavior and deliver targeted promotions.
ip
ip
Type number
Description
The user's IP address.
Guidance
- Typically included in the response from our API
- Useful for geographical targeting.
- Can be specified in IPv4 or IPv6 format.
DeltasObject
DeltasObject
session_time
session_time
Type number
Description
The amount of time the user has had the app open is measured in seconds.
Guidance
- Use this metric to track user engagement and app usage patterns over time.
session_count
session_count
Type number
Description
The number of times the user has opened the app.
Guidance
- This metric helps you to identify users who should be re-engaged.
- Defaults to
2
if no previous sessions are recorded.
purchases
purchases
Type object
See PurchasesObject for details.
PurchasesObject
PurchasesObject
sku
sku
Type string
Description
The stock-keeping unit (SKU) identifier for the purchased item.
Guidance
- Use this identifier to track specific items purchased by the user.
- Defaults to
item
if not specified.
iso
iso
Type string
Description
Currency code in ISO 4217 format.
Guidance
• Specify the currency used for the transaction. Ensure it aligns with the user’s location and preferences.
amount
amount
Type number
Description
The amount spent on the purchase.
Guidance
-
Specify the monetary value of the purchase, formatted as a decimal.
-
Defaults to
33.33
count
count
Type number
Description
The number of units purchased.
Guidance
- Track the number of items purchased to better understand user behavior and preferences.
- Defaults to
3
if not specified.