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:

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


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.

Language