Skip to main content
A Test User is one or more Subscriptions you designate for testing message delivery. Test Users have a dedicated segment filter and can be targeted from the message composer, in Journey audiences, and in webhook tests.

​
Finding your Subscription

Go to Audience > Subscriptions in the OneSignal Dashboard and search by any of these identifiers:
  • External ID (preferred): the user ID from your database, CRM, or other system of record.
  • Email: if you send email addresses to OneSignal.
  • Phone number: if you send phone numbers to OneSignal.
  • Subscription ID or OneSignal ID: available in your app logs. See the SDK properties OneSignal.User.onesignalId and OneSignal.User.pushSubscription.id.
If you don’t have any of these identifiers, find your Subscription by device and IP:
  1. Note your device make and model (for example, “iPhone 17 Pro”).
  2. Find your IP address (not tracked in the EU or when IP tracking is disabled). On the device, open a browser and search “What is my IP address?”. Note both the IPv4 and IPv6 values if provided.
  3. Go to Audience > Subscriptions and sort by Last session to see the most recently active Subscriptions.
  4. Open the app on your device and wait a few seconds.
  5. Refresh the Subscriptions list. Your Subscription matches your device and IP.
If you don’t see the Last session, Device, or IP address columns, toggle them on with the Columns button.
Columns button and the Last session, Device, and IP address columns
Ask your app developer which identifiers your app passes to OneSignal, and have them set an External ID if they aren’t already. Email support@onesignal.com if you’re still stuck.

​
Mark a User as a test user

​
From a Subscription

Use this flow when you have your device’s Subscription ID or want to find your device by activity.
  1. Go to Audience > Subscriptions and find the Subscription for the device you want to test with.
  2. Next to the Subscription, select Options > Add as test user.
  3. Enter a test user name.
Options menu on a subscription record with Add as test user highlighted

​
When manually creating a User

When adding a single User through the dashboard’s New User form, check Add as test user and provide a name. All Subscriptions created for this User are marked as test users under that name.

​
Via the API

Set the test_user_name property when creating or updating a User with the REST API: 
curl -X POST https://api.onesignal.com/apps/YOUR_APP_ID/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -d '{
    "properties": {
      "test_user_name": "QA Device - Jane"
    }
  }'

curl -X PATCH https://api.onesignal.com/apps/YOUR_APP_ID/users/by/{alias_label}/{alias_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -d '{
    "properties": {
      "test_user_name": "QA Device - Jane"
    }
  }'
To clear the test user name, set test_user_name to an empty string (""). See Create user and Update user for the full API reference.

​
Send to test users

Once a User is marked as a test user, you can send to them from:

​
FAQ

​
How do I remove a test user?

From the dashboard:
  • From the User profile: Open the User and select Actions > Remove as test user.
  • From the Subscriptions list: Go to Audience > Subscriptions, find any Subscription belonging to the User, then select Options > Remove as test user.
Either action clears the test flag from the User and all of their Subscriptions. The User and Subscriptions remain in your app but are no longer marked as test users. You can also clear the flag via the API by setting test_user_name to "" on the User.

​
What’s the difference between a test user and a test subscription?

None. Test status is stored on the User, so marking any one Subscription as a test user marks the underlying User and applies the flag to all of that User’s other Subscriptions.

​
My test user has a subscription that shows as unsubscribed. How do I re-subscribe them?

Manually re-subscribe from the User profile > Subscriptions tab.
User profile Subscriptions tab with the manual re-subscribe option
Re-subscribing a user without their consent violates messaging compliance rules and can result in spam complaints, carrier filtering, or account suspension.

​
Why does the same person appear multiple times in the Test Users filter?

Each app reinstall creates a new Subscription. Without an External ID linking that Subscription to the existing User, OneSignal creates a new User for it. Call OneSignal.login with the same External ID after install to link the Subscription to the existing User.

​
Can I send to test users from the API?

Yes. Use the Create notification API with include_subscription_ids to target specific test devices, or with included_segments: ["Test Users"] to target every test user in the app.

Users

The OneSignal user model, aliases, and how Users relate to Subscriptions.

Subscriptions

Manage Subscriptions and find a specific device for testing.

Segmentation

Build segments, including a Test Users segment, to scope sends.

Create message API

Send notifications programmatically to specific Subscription IDs.