GET
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
curl --request GET \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id} \
  --header 'Authorization: <authorization>'
"{\n  \"properties\": {\n      \"tags\": {\n          \"KEY\": \"VALUE\"\n      },\n      \"country\": \"US\",\n      \"first_active\": 1673449251,\n      \"last_active\": 1678126124\n  },\n  \"identity\": {\n      \"external_id\": \"example123\",\n      \"onesignal_id\": \"ONESIGNAL_ID\"\n  },\n  \"subscriptions\": [\n    {\n      \"id\": \"SUBSCRIPTION_ID\",\n      \"app_id\": \"APP_ID\",\n      \"type\": \"Email\",\n      \"token\": \"example@example.com\",\n      \"enabled\": true,\n      \"notification_types\": -99,\n      \"session_time\": 3670,\n      \"session_count\": 129,\n      \"sdk\": \"\",\n      \"device_model\": \"\",\n      \"device_os\": \"\",\n      \"rooted\": false,\n      \"test_type\": 0,\n      \"app_version\": \"\",\n      \"net_type\": 0,\n      \"carrier\": \"\",\n      \"web_auth\": \"\",\n      \"web_p256\": \"\"\n    }\n  ]\n}"

​
Overview

  • Use this API to retrieve a user’s full profile, including identity aliases, user properties, and messaging subscription details across channels.
  • This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see Users, Subscriptions, and Aliases documentation.

​
How to use this API

To look up a user, you must provide both an alias_label and an alias_id. In most cases, your external_id will serve as the alias_label, and its value will be passed as the alias_id. While you may use a custom alias, we strongly recommend setting and using the external_id as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the alias_label to onesignal_id. Note: When querying with any alias other than onesignal_id, authentication is required.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

​
app_id
string
required

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

​
alias_label
string
required

The alias name or key to locate the user. Most commonly set as external_id but can be the onesignal_id or a custom alias.

​
alias_id
string
required

The specific identifier for the given alias to identify the user.

Response

200
application/json

200

The response is of type object.

GET
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
curl --request GET \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id} \
  --header 'Authorization: <authorization>'
"{\n  \"properties\": {\n      \"tags\": {\n          \"KEY\": \"VALUE\"\n      },\n      \"country\": \"US\",\n      \"first_active\": 1673449251,\n      \"last_active\": 1678126124\n  },\n  \"identity\": {\n      \"external_id\": \"example123\",\n      \"onesignal_id\": \"ONESIGNAL_ID\"\n  },\n  \"subscriptions\": [\n    {\n      \"id\": \"SUBSCRIPTION_ID\",\n      \"app_id\": \"APP_ID\",\n      \"type\": \"Email\",\n      \"token\": \"example@example.com\",\n      \"enabled\": true,\n      \"notification_types\": -99,\n      \"session_time\": 3670,\n      \"session_count\": 129,\n      \"sdk\": \"\",\n      \"device_model\": \"\",\n      \"device_os\": \"\",\n      \"rooted\": false,\n      \"test_type\": 0,\n      \"app_version\": \"\",\n      \"net_type\": 0,\n      \"carrier\": \"\",\n      \"web_auth\": \"\",\n      \"web_p256\": \"\"\n    }\n  ]\n}"

​
Overview

  • Use this API to retrieve a user’s full profile, including identity aliases, user properties, and messaging subscription details across channels.
  • This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see Users, Subscriptions, and Aliases documentation.

​
How to use this API

To look up a user, you must provide both an alias_label and an alias_id. In most cases, your external_id will serve as the alias_label, and its value will be passed as the alias_id. While you may use a custom alias, we strongly recommend setting and using the external_id as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the alias_label to onesignal_id. Note: When querying with any alias other than onesignal_id, authentication is required.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

​
app_id
string
required

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

​
alias_label
string
required

The alias name or key to locate the user. Most commonly set as external_id but can be the onesignal_id or a custom alias.

​
alias_id
string
required

The specific identifier for the given alias to identify the user.

Response

200
application/json

200

The response is of type object.