🚧
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`

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`

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`

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`

Type object

See DeltasObject for details.

Description

User properties that change frequently and generally only increment.

Request Object Definitions

`UserProperties`

The UserProfile object represents a user's profile data, including tags, user activity, and other relevant properties.

`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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

`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`

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`

Type object

See PurchasesObject for details.

`PurchasesObject`

`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`

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`

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`

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.

🚧Compatibility with Pre-User Model SDKs and APIs

Overview

How to Use this API

What Can Be Updated?

Examples

Update user via OneSignal ID

Update user via Alias (requires auth)

Path Parameters

alias_label

alias_id

Body Parameters

properties

deltas

Request Object Definitions

UserProperties

tags

language

timezone_id

lat

long

country

first_active

last_active

purchases

ip

DeltasObject

session_time

session_count

purchases

PurchasesObject

sku

iso

amount

count

🚧
Compatibility with Pre-User Model SDKs and APIs

`alias_label`

`alias_id`

`properties`

`deltas`

`UserProperties`

`tags`

`language`

`timezone_id`

`lat`

`long`

`country`

`first_active`

`last_active`

`purchases`

`ip`

`DeltasObject`

`session_time`

`session_count`

`purchases`

`PurchasesObject`

`sku`

`iso`

`amount`

`count`