Server REST API Reference
Log InSign Up

Update user

patch https://api.onesignal.com/apps//users/by//

Modify a user's properties.

🚧

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

Use this API to update properties on existing users within a specific OneSignal app.

If you want to update the user's identity like external_id or custom Aliases, use the Create alias and Delete alias APIs.

If you want to update a user's subscriptions, use the Create subscription (by alias) or Create user APIs.

How to use this API

You must first have a User created.

Identify your user

To update a user, they must be identifiable via the alias_label and alias_id in the path parameters. The most commonly used and recommended alias is the external_id, but you can also use the onesignal_id or a custom alias. See Users and Aliases for details.

Update properties

This API does not update the user's identity

Body parameters

properties

Type object

Description

Lets you specify user data, including tags and activity.

User data helps you personalize your user experience, track user behavior, and improve engagement through targeted push notifications, emails, and text messages.

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


User properties definitions (click to expand)

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.

  • 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.

  • 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".

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • Use this field to gauge user engagement and inactivity to and trigger re-engagement campaigns.

ip

Type number

Description

The user's IP address.

  • Typically included in the response from our API
  • Useful for geographical targeting.
  • Can be specified in IPv4 or IPv6 format.

Example

{
  "properties": {
    "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

Description

User properties that change frequently and generally only increment.

User deltas definitions (click to expand)

session_time

Type number

Description

The amount of time the user has had the app open is measured in seconds.

  • 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.

  • This metric helps you to identify users who should be re-engaged.

purchases

Type object

Description

A list of SKUs with purchase data. If using our SDKs, we only collect consumable in-app purchases for mobile apps.

If you have subscription-based purchases, a website, email-only, and/or SMS-only users, then you should consider using Data Tags instead.

sku

Type string

Description

The stock-keeping unit (SKU) identifier for the purchased item.

  • 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.

• 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.

  • Specify the monetary value of the purchase, formatted as a decimal.

count

Type number

Description

The number of units purchased.

  • Track the number of items purchased to better understand user behavior and preferences.
Language