Register a new Subscription (aka player) to one of your OneSignal apps.

This is a Legacy API. Use Create User or Create Subscription instead.

​
Headers

HeaderValueRequiredDescription
Content-Typeapplication/jsonYesThe content type of the request.
AuthorizationBasic YOUR_REST_API_KEYYesYour OneSignal REST API key.

​
Request Body Parameters

FieldTypeRequiredDescription
app_idstringYesYour OneSignal App ID.
device_typeintegerYesDevice platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc.
identifierstringNoPush token, email address, or phone number.
languagestringNoLanguage code (e.g. “en”).
timezoneintegerNoTime zone offset in seconds.
game_versionstringNoVersion of your app.
device_modelstringNoDevice model (e.g., “iPhone12,1”).
device_osstringNoOperating system version (e.g., “13.3”).
ad_idstringNoAdvertising ID.
sdkstringNoOneSignal SDK version (e.g., “050201” for 5.2.1).
session_countintegerNoNumber of times the user has used the app.
tagsobjectNoCustom tags as key-value pairs.
external_user_idstringNoYour system’s user ID for this device.
notification_typesintegerNo1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.

​
Example Request

POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}

​
Response

{
  "id": "Subscription_id_string"
}

​
Errors

  • 400 Bad Request – Invalid parameters or missing required fields.
  • 401 Unauthorized – Invalid or missing API key.
  • 403 Forbidden – Not allowed for your account type or plan.