> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# View user identity (by subscription)

> Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


## OpenAPI

````yaml GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
openapi: 3.1.0
info:
  title: api.onesignal.com
  version: '11.6'
servers:
  - url: https://api.onesignal.com
security:
  - {}
paths:
  /apps/{app_id}/subscriptions/{subscription_id}/user/identity:
    get:
      summary: View user identity (by subscription)
      description: >-
        Retrieve all aliases linked to a user using a known `subscription_id`.
        This is useful when the user’s identity is unknown but you have access
        to one of their push, email, or SMS subscriptions.
      operationId: fetch-identity-by-subscription
      parameters:
        - name: app_id
          in: path
          description: >-
            Your OneSignal App ID in UUID v4 format. See [Keys &
            IDs](/docs/en/keys-and-ids).
          schema:
            type: string
          required: true
        - name: subscription_id
          in: path
          description: >-
            The unique Subscription ID in UUID v4 format generated by OneSignal.
            See [Subscriptions](/docs/subscriptions).
          schema:
            type: string
          required: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  identity:
                    type: object
                    properties:
                      onesignal_id:
                        type: string
                        description: >-
                          The OneSignal ID of the user. See
                          [Users](/docs/users).
                        example: OneSignal-ID-in-UUID-v4-format
                      external_id:
                        type: string
                        description: The External ID of the user. See [Users](/docs/users).
                        example: the-users-external-id
                      custom_alias_label:
                        type: string
                        description: >-
                          A custom alias of the user. See
                          [Aliases](/docs/aliases).
                        example: the-users-custom-alias-id
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
              example:
                errors:
                  - code: internal error code
                    title: example error title
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
              example:
                errors:
                  - code: internal error code
                    title: example error title
        '429':
          description: >-
            Rate limit exceeded. Wait the number of seconds in the `Retry-After`
            header before retrying.
          headers:
            Retry-After:
              description: >-
                Number of seconds to wait before retrying the request. Always
                emitted on 429 responses.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
              example:
                errors:
                  - code: Rate Limit Exceeded
                    title: API rate limit exceeded
        '503':
          description: >-
            Service temporarily unavailable. Retry after a short backoff. The
            body may be empty or non-JSON in some failure modes.
          headers:
            Retry-After:
              description: >-
                Number of seconds to wait before retrying. Optional — may be
                absent when the response is generated upstream.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorResponse'
              example:
                errors:
                  - Service temporarily unavailable
      deprecated: false
components:
  schemas:
    StructuredErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/StructuredErrorItem'
    BasicErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: One or more human-readable error messages.
        success:
          type: boolean
          description: >-
            Present (and `false`) on some endpoints (notifications, templates,
            segments). Not emitted by every endpoint.
        reference:
          type: array
          items:
            type: string
          description: >-
            Documentation URL fragments related to the error. Only emitted by
            the API-key auth error helpers.
    StructuredErrorItem:
      type: object
      required:
        - code
        - title
      properties:
        code:
          type: string
          description: >-
            Stable error-code identifier. Use this for programmatic branching in
            your integration.
        title:
          type: string
          description: >-
            Human-readable error message intended for logs and operator-facing
            surfaces.
        meta:
          type: object
          additionalProperties: true
          description: >-
            Optional structured details about this specific error. The shape of
            `meta` varies by `code` — for example, the create-user `Conflict`
            code returns `{ conflicting_aliases: { [alias_label]: alias_id } }`.

````