Skip to main content

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.

A test user is a User you designate for testing message delivery. Test users have a dedicated segment filter and can be targeted directly from the message composer, in Journey audiences, and in webhook tests. The test flag is a User-level property: marking a User as a test user automatically applies to all of their Subscriptions under the same test name. You can mark a User as a test user from the User profile, when manually creating a User, from any of their Subscriptions, or through the API.
Options menu on a subscription record with Add as test user highlighted

​
Mark a User as a test user

​
From the User profile

Use this flow when you already know the User and want to mark them as a test user without finding a specific Subscription.
  1. Go to Audience > Users and open the User’s profile.
  2. Select Actions > Add as test user.
  3. Enter a test user name. All Subscriptions linked to this User are added as test users under the same name.

​
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 will be marked as test users under that name.

​
From a Subscription

Use this flow when you have your device’s Subscription ID or want to find your device by activity. Marking a Subscription as a test user marks the underlying User as a test user, which propagates to all of their other Subscriptions.
  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.

​
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" \
  -d '{
    "properties": {
      "test_user_name": "QA Device - Jane"
    }
  }'
To remove the test user label, 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 Options > Remove as test user.
  • From the Subscriptions list: Go to Audience > Subscriptions, find any Subscription belonging to the User, then select Options > Remove from Test Users.
Either action clears the test flag from the User and all of their Subscriptions. The User and Subscriptions remain in your app, they’re just 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 user?

There is no longer a meaningful difference. Test status is stored on the User, so marking any one Subscription as a test user marks the underlying User as a test user, which applies the flag to all of that User’s other Subscriptions. The “Add as test user” entry point on the Subscriptions list is preserved for convenience.

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

The simplest option is to manually re-subscribe on 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. If the new Subscription isn’t linked to the existing User via External ID, it shows up as a separate User. Call OneSignal.login with the same External ID after install to keep all of a person’s Subscriptions tied to one User.

​
Can I send to test users from the API?

Yes. Use the Create notification API with include_subscription_ids and pass the Subscription IDs of your test devices.

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.