POST
/
apps
/
{app_id}
/
users
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/users \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "tags": {},
    "language": "en",
    "timezone_id": "America\\/Los_Angeles",
    "lat": 123,
    "long": 123,
    "country": "US",
    "first_active": 123,
    "last_active": 123,
    "ip": "<string>"
  },
  "identity": {
    "external_id": "<string>"
  },
  "subscriptions": [
    {
      "type": "Email",
      "token": "<string>",
      "enabled": true,
      "notification_types": 123,
      "session_time": 123,
      "session_count": 123,
      "app_version": "<string>",
      "device_model": "<string>",
      "device_os": "<string>",
      "test_type": 123,
      "sdk": "<string>",
      "rooted": true,
      "web_auth": "<string>",
      "web_p256": "<string>"
    }
  ]
}'
"{\n  \"identity\": {\n    \"onesignal_id\": \"567491ee-9105-4a87-9cbc-ed78a571645b\"\n  },\n  \"properties\": {\n    \"tags\": {\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\"\n    }\n  }\n}"

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 enables you to create and manage users outside of frontendSDK-based sessions. It’s primarily used to:

  • Import users from other systems.
  • Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you’re using the frontend SDKs, user creation is typically handled automatically via methods like login, addEmail, and addSms. See Users and Subscriptions for conceptual guidance.

​
How to use this API

To successfully create a user via the API:

  • You must provide at least one unique identifier via the identity and Subscription via the subscriptions fields.
  • You can optionally include user profile data (properties) and one or more messaging subscriptions.

​
Key Concepts

​
Aliases

Aliases uniquely identify a user and should include an external_id (the recommended identifier). Up to 20 custom aliases are supported. They allow you to reference users across platforms or external systems.

​
Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

​
Subscriptions

A user can have up to 20 subscriptions (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See Subscriptions for more.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Body

application/json

Response

200
application/json

200

The response is of type object.

POST
/
apps
/
{app_id}
/
users
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/users \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "tags": {},
    "language": "en",
    "timezone_id": "America\\/Los_Angeles",
    "lat": 123,
    "long": 123,
    "country": "US",
    "first_active": 123,
    "last_active": 123,
    "ip": "<string>"
  },
  "identity": {
    "external_id": "<string>"
  },
  "subscriptions": [
    {
      "type": "Email",
      "token": "<string>",
      "enabled": true,
      "notification_types": 123,
      "session_time": 123,
      "session_count": 123,
      "app_version": "<string>",
      "device_model": "<string>",
      "device_os": "<string>",
      "test_type": 123,
      "sdk": "<string>",
      "rooted": true,
      "web_auth": "<string>",
      "web_p256": "<string>"
    }
  ]
}'
"{\n  \"identity\": {\n    \"onesignal_id\": \"567491ee-9105-4a87-9cbc-ed78a571645b\"\n  },\n  \"properties\": {\n    \"tags\": {\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\"\n    }\n  }\n}"

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 enables you to create and manage users outside of frontendSDK-based sessions. It’s primarily used to:

  • Import users from other systems.
  • Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you’re using the frontend SDKs, user creation is typically handled automatically via methods like login, addEmail, and addSms. See Users and Subscriptions for conceptual guidance.

​
How to use this API

To successfully create a user via the API:

  • You must provide at least one unique identifier via the identity and Subscription via the subscriptions fields.
  • You can optionally include user profile data (properties) and one or more messaging subscriptions.

​
Key Concepts

​
Aliases

Aliases uniquely identify a user and should include an external_id (the recommended identifier). Up to 20 custom aliases are supported. They allow you to reference users across platforms or external systems.

​
Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

​
Subscriptions

A user can have up to 20 subscriptions (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See Subscriptions for more.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Body

application/json

Response

200
application/json

200

The response is of type object.