---
title: "Create user"
method: POST
path: "/apps/{app_id}/users"
---

# Create user

`POST /apps/{app_id}/users`

Create a new user or modify the subscriptions associated with an existing User.

## Path parameters

- `app_id` string, required

## Request body

- object
  - `properties` object — Represents user profile data for a given user, including tags, preferences, user activity, and other valuable properties.
    - `tags` object — Custom user events or properties made of key-value pairs of string values. See [Tags](/docs/en/add-user-data-tags). Does not support arrays or other nested objects. Example: `{'foo':'bar','this':'that'}`
    - `language` string — Language Abbreviation in ISO 639-1 format. See [supported languages](/docs/en/multi-language-messaging#supported-languages). Must be lower-case.
    - `timezone_id` string — Timezone ID based on the [tz database "TZ identifier"](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
    - `lat` number, float — User's current latitude. Acceptable values range between `-90` to `90`.
    - `long` number, float — User's current longitude. Acceptable values range between `-180` to `180`.
    - `country` string — Country code in [ISO 3166-1 Alpha 2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Must be upper-case.
    - `first_active` integer — Unix timestamp in seconds representing when the user was created.
    - `last_active` integer — Unix timestamp in seconds representing the most recent time the user was active in your app.
    - `ip` string — IPv4 or IPv6, response only
    - `test_user_name` string — A label for marking this user as a [Test user](/docs/en/test-users).
  - `identity` object — Defines identifiers for the user. The `external_id` must be used and should be unique across users.
    - `external_id` string — The main user ID to identify the user. See [Users](/docs/users).
  - `subscriptions` object[] — The subscriptions object allows for creating or transferring subscriptions to a specified user. See [Subscriptions](/docs/subscriptions).
    - `type` 'Email' | 'SMS' | 'iOSPush' | 'AndroidPush' | 'HuaweiPush' | 'FireOSPush' | 'WindowsPush' | 'macOSPush' | 'ChromePush' | 'FirefoxPush' | 'SafariPush', required — The subscription channel type. Must match the format of the token..
    - `token` string, required — The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.
    - `enabled` boolean — Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed.
    - `notification_types` integer — Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).
    - `session_time` integer — The total amount of time the user has had the app open in seconds.
    - `session_count` integer — The total amount of times the user has opened the app.
    - `app_version` string — The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version.
    - `device_model` string — The model of the user's device (e.g., iPhone 16).
    - `device_os` string — The device or browser's system version.
    - `test_type` integer — Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.
    - `sdk` string — Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version.
    - `web_auth` string — The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal).
    - `web_p256` string — The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal).

## Response `200`

200

- object
  - `identity` object
    - `onesignal_id` string
  - `properties` object
    - `tags` object
      - `first_name` string
      - `last_name` string

## Other responses

- `202` — 202
- `400` — 400
- `409` — Conflict. The request's claimed identity (one or more aliases or external_id) is already bound to a different user. `errors[].meta.conflicting_aliases` lists each colliding alias label and the conflicting alias ID.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)