GET
/
apps
/
{app_id}
/
users
/
by
/
{alias_label}
/
{alias_id}
/
identity
curl --request GET \
  --url https://api.onesignal.com/apps/{app_id}/users/by/{alias_label}/{alias_id}/identity \
  --header 'Authorization: <authorization>'
"{\n  \"identity\": {\n    \"onesignal_id\": \"27d9de62-4e7b-4809-a856-bf279288bbda\",\n    \"external_id\": \"my-external-id\"\n  }\n}"

​
Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the View user API but only returns the identity object—not subscriptions or properties.

If you only know a subscription_id, use View user identity (by subscription) instead.

For more context on user identity and aliasing:

​
How to use this API

To identify the user, use:

  • alias_label – the type of alias you’re using to find the user (e.g. external_id, onesignal_id, or a custom alias)
  • alias_id – the actual value of that alias

Common usage patterns:

Using external_id (recommended):

  • alias_label: external_id
  • alias_id: your user ID (e.g., user-123)

Using onesignal_id:

  • alias_label: onesignal_id
  • alias_id: the OneSignal-assigned unique ID

Using a custom alias:

  • Define your own alias label (e.g. shopify_customer_id) and its value

We strongly recommend setting and using the external_id as your primary user identifier for portability and simplicity across your systems.

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.