> ## 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 > Retrieve a user including aliases, properties, and subscriptions. ## 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](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/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. *** ## OpenAPI ````yaml GET /apps/{app_id}/users/by/{alias_label}/{alias_id} openapi: 3.1.0 info: title: api.onesignal.com version: '11.6' servers: - url: https://api.onesignal.com security: - {} paths: /apps/{app_id}/users/by/{alias_label}/{alias_id}: get: summary: View user description: Retrieve a user including aliases, properties, and subscriptions. operationId: view-user 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: alias_label in: path description: >- 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](/docs/aliases). schema: type: string required: true - name: alias_id in: path description: The specific identifier for the given alias to identify the user. schema: type: string required: true - name: Authorization in: header description: >- Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids). required: true schema: type: string default: Key YOUR_APP_API_KEY responses: '200': description: '200' content: application/json: examples: Result: value: properties: tags: KEY: VALUE country: US first_active: 1673449251 last_active: 1678126124 test_user_name: QA Device - Jane identity: external_id: example123 onesignal_id: ONESIGNAL_ID subscriptions: - id: SUBSCRIPTION_ID app_id: APP_ID type: Email token: example@example.com enabled: true notification_types: -99 session_time: 3670 session_count: 129 sdk: '' device_model: '' device_os: '' rooted: false test_type: 0 app_version: '' net_type: 0 carrier: '' web_auth: '' web_p256: '' schema: type: object properties: properties: type: object properties: tags: type: object properties: KEY: type: string example: VALUE country: type: string example: US first_active: type: integer example: 1673449251 default: 0 last_active: type: integer example: 1678126124 default: 0 test_user_name: type: string example: QA Device - Jane identity: type: object properties: external_id: type: string example: example123 onesignal_id: type: string example: ONESIGNAL_ID subscriptions: type: array items: type: object properties: id: type: string description: The unique Subscription ID in UUID v4 format. app_id: type: string descriptions: >- Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids). type: type: string description: The subscription channel type. token: type: string description: >- The push token, email address, or phone number associated with the subscription. enabled: type: boolean description: >- Indicates if the Subscription is subscribed (`true`) or unsubscribed (`false`). notification_types: type: integer description: >- Indicates the reason for the Subscription's status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types). session_time: type: integer description: >- The total amount of time the user has had the app open in seconds. format: int32 session_count: type: integer description: >- The total amount of times the user has opened the app. format: int32 sdk: type: string description: >- Set by our frontend SDK. Indicates the OneSignal SDK version. device_model: type: string description: The model of the user's device (e.g., iPhone 16). device_os: type: string description: The device or browser's system version. rooted: type: boolean description: Indicates if the Android device is jail-broken. test_type: type: integer description: >- Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment. format: int32 app_version: type: string description: >- The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version. net_type: type: integer example: 0 default: 0 carrier: type: string example: '' web_auth: type: string description: The web auth token set by our web SDK. web_p256: type: string description: The web 256 key set by our web SDK. '400': description: '400' content: application/json: examples: Result: value: errors: - code: internal error code title: example error title meta: {} schema: $ref: '#/components/schemas/StructuredErrorResponse' '401': description: '401' content: application/json: examples: Result: value: errors: - code: auth-1 title: >- This operation requires 'Authorization' in the HTTP header schema: $ref: '#/components/schemas/StructuredErrorResponse' '404': description: '404' content: application/json: examples: Result: value: errors: - code: internal error code title: example error title meta: {} schema: $ref: '#/components/schemas/StructuredErrorResponse' '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 x-codeSamples: - lang: typescript label: Node.js SDK source: |- import Onesignal from '@onesignal/node-onesignal'; const configuration = Onesignal.createConfiguration({ restApiKey: '', }); const apiInstance = new Onesignal.DefaultApi(configuration); // string const appId: string = "00000000-0000-0000-0000-000000000000"; // string const aliasLabel: string = "external_id"; // string const aliasId: string = "YOUR_USER_EXTERNAL_ID"; try { const response = await apiInstance.getUser(appId, aliasLabel, aliasId); console.log(response); } catch (e) { if (e instanceof Onesignal.ApiException) { // `e.errorMessages` flattens any error-envelope shape to a `string[]`; // the raw parsed body remains on `e.body`. console.error("getUser failed: HTTP " + e.code, e.errorMessages); } else { throw e; } } - lang: python label: Python SDK source: >- import onesignal from onesignal.api import default_api from onesignal.models import * from pprint import pprint # See configuration.py for a list of all supported configuration parameters. # Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY. # We recommend adding both of them in the configuration page so that you will not need to figure it out yourself. configuration = onesignal.Configuration( rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints organization_api_key = "YOUR_ORGANIZATION_KEY" # Organization key is only required for creating new apps and other top-level endpoints ) # Enter a context with an instance of the API client with onesignal.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = default_api.DefaultApi(api_client) app_id = "00000000-0000-0000-0000-000000000000" alias_label = "external_id" alias_id = "YOUR_USER_EXTERNAL_ID" # example passing only required values which don't have defaults set try: api_response = api_instance.get_user(app_id, alias_label, alias_id) pprint(api_response) except onesignal.ApiException as e: print("Exception when calling DefaultApi->get_user: %s\n" % e) print("Status Code: %s" % e.status) print("Response Body: %s" % e.body) - lang: php label: PHP SDK source: |- setRestApiKeyToken('YOUR_REST_API_KEY') ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY'); $apiInstance = new onesignal\client\Api\DefaultApi( // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`. // This is optional, `GuzzleHttp\Client` will be used as default. new GuzzleHttp\Client(), $config ); $app_id = '00000000-0000-0000-0000-000000000000'; // string $alias_label = 'external_id'; // string $alias_id = 'YOUR_USER_EXTERNAL_ID'; // string try { $result = $apiInstance->getUser($app_id, $alias_label, $alias_id); print_r($result); } catch (\onesignal\client\ApiException $e) { echo 'Exception when calling DefaultApi->getUser: ', $e->getMessage(), PHP_EOL; echo 'Status Code: ', $e->getCode(), PHP_EOL; // getErrorMessages() flattens any error-envelope shape to a string[]; // the raw body remains on getResponseBody(). echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL; echo 'Response Body: ', $e->getResponseBody(), PHP_EOL; } catch (\Exception $e) { echo 'Exception when calling DefaultApi->getUser: ', $e->getMessage(), PHP_EOL; } - lang: go label: Go SDK source: |- package main import ( "context" "fmt" "os" "github.com/OneSignal/onesignal-go-api/v5" ) func main() { appId := "00000000-0000-0000-0000-000000000000" // string | aliasLabel := "external_id" // string | aliasId := "YOUR_USER_EXTERNAL_ID" // string | configuration := onesignal.NewConfiguration() apiClient := onesignal.NewAPIClient(configuration) restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints resp, r, err := apiClient.DefaultApi.GetUser(restAuth, appId, aliasLabel, aliasId).Execute() if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.GetUser``: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok { // ErrorMessages() flattens any error-envelope shape to a []string; // the raw body remains on Body(). fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages()) fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body()) } } // response from `GetUser`: User fmt.Fprintf(os.Stdout, "Response from `DefaultApi.GetUser`: %v\n", resp) } - lang: ruby label: Ruby SDK source: |- require 'onesignal' # setup authorization OneSignal.configure do |config| # Configure Bearer authorization: rest_api_key config.rest_api_key = 'YOUR_BEARER_TOKEN' end api_instance = OneSignal::DefaultApi.new app_id = '00000000-0000-0000-0000-000000000000' # String | alias_label = 'external_id' # String | alias_id = 'YOUR_USER_EXTERNAL_ID' # String | begin result = api_instance.get_user(app_id, alias_label, alias_id) p result rescue OneSignal::ApiError => e puts "Error when calling DefaultApi->get_user: #{e}" puts "Status Code: #{e.code}" # `e.error_messages` flattens any error-envelope shape to an Array; # the raw body remains on `e.response_body`. puts "Error Messages: #{e.error_messages}" puts "Response Body: #{e.response_body}" end - lang: java label: Java SDK source: |- // Import classes: import com.onesignal.client.ApiClient; import com.onesignal.client.ApiException; import com.onesignal.client.Configuration; import com.onesignal.client.auth.*; import com.onesignal.client.model.*; import com.onesignal.client.api.DefaultApi; public class Example { public static void main(String[] args) { ApiClient defaultClient = Configuration.getDefaultApiClient(); defaultClient.setBasePath("https://api.onesignal.com"); // Configure HTTP bearer authorization: rest_api_key HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key"); rest_api_key.setBearerToken("BEARER TOKEN"); DefaultApi apiInstance = new DefaultApi(defaultClient); String appId = "00000000-0000-0000-0000-000000000000"; // String | String aliasLabel = "external_id"; // String | String aliasId = "YOUR_USER_EXTERNAL_ID"; // String | try { User result = apiInstance.getUser(appId, aliasLabel, aliasId); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling DefaultApi#getUser"); System.err.println("Status code: " + e.getCode()); // getErrorMessages() flattens any error-envelope shape to a List; // the raw body remains on getResponseBody(). System.err.println("Error messages: " + e.getErrorMessages()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } - lang: csharp label: C# SDK source: |- using System; using System.Collections.Generic; using System.Diagnostics; using OneSignalApi.Api; using OneSignalApi.Client; using OneSignalApi.Model; namespace Example { public class GetUserExample { public static void Main() { Configuration config = new Configuration(); config.BasePath = "https://api.onesignal.com"; // Configure Bearer token for authorization: rest_api_key config.AccessToken = "YOUR_BEARER_TOKEN"; var apiInstance = new DefaultApi(config); var appId = "00000000-0000-0000-0000-000000000000"; // string | var aliasLabel = "external_id"; // string | var aliasId = "YOUR_USER_EXTERNAL_ID"; // string | try { User result = apiInstance.GetUser(appId, aliasLabel, aliasId); Debug.WriteLine(result); } catch (ApiException e) { Debug.Print("Exception when calling DefaultApi.GetUser: " + e.Message ); Debug.Print("Status Code: "+ e.ErrorCode); // e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList; // the raw body remains on e.ErrorContent. Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages)); Debug.Print("Response Body: " + e.ErrorContent); Debug.Print(e.StackTrace); } } } } - lang: rust label: Rust SDK source: |- use onesignal_rust_api::apis::configuration::Configuration; use onesignal_rust_api::apis::default_api; #[tokio::main] async fn main() { let mut configuration = Configuration::new(); configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string()); // Realistic values are pulled from the spec's `example:` fields where present. let app_id: &str = "00000000-0000-0000-0000-000000000000"; let alias_label: &str = "external_id"; let alias_id: &str = "YOUR_USER_EXTERNAL_ID"; match default_api::get_user(&configuration, app_id, alias_label, alias_id).await { Ok(resp) => println!("{:?}", resp), Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => { // `e.error_messages()` flattens any error-envelope shape to a Vec; // the raw response remains on the ResponseError variant. eprintln!("get_user failed: {:?}", e.error_messages()); } Err(e) => eprintln!("get_user failed: {:?}", e), } } 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 } }`. ````