Benefits of integrating with OneSignal
As a OneSignal partner, you’ll gain valuable benefits aligned with your integration success and engagement:- Visibility and recognition: Showcase your integration through a verified listing in the OneSignal Partner Directory, with opportunities for increased exposure and “featured” listings as your partnership grows.
- Enhanced collaboration: Participate in joint co-marketing activities, co-selling initiatives, and access comprehensive training to maximize integration adoption.
- Strategic support: Gain direct access to our dedicated support and technical teams, with additional levels of support unlocked based on partnership milestones.
- Growth opportunities: Access progressively advanced partner benefits such as dedicated documentation pages, enterprise sandbox accounts, and prioritized marketing opportunities as you expand your customer base and reach specific partnership milestones.
Getting started
To start developing your integration, create a free account at onesignal.com. To join the partner program or to request premium features for integration development and testing, reach out through partners.onesignal.com or emailbd@onesignal.com.
Requirement: OneSignal-Usage header
To join the partner program, you must include the OneSignal-Usage header in all API requests. This header lets OneSignal identify your integration, provide better support, and track adoption across mutual customers.
Format:
<YourCompany> with your company or platform name. For example, if your company is Acme, use Acme | Partner Integration.
Submit your integration for verification
Once your integration is ready, complete the Partner Validation Request form to open a request ticket with the Partnerships team. Verification formally recognizes your integration on OneSignal’s side, enabling full access to the Integration Partner Program. Before submitting, run through the end-to-end verification checklist.Partner architecture patterns
Most OneSignal partner integrations fall into one of three architectural patterns. Identify which one you are building before deciding how to handle identity, Subscription creation, and event timing.| Pattern | Examples | Where External ID is set | What your integration writes |
|---|---|---|---|
| Server-side webhook | Attribution platforms, marketing automation tools | Customer’s app, via the OneSignal SDK | Aliases, tags, custom events (after External ID exists) |
| CDP-style sync | Segment, RudderStack, mParticle | Your sync calls Create user with external_id from upstream sources | Users, aliases, tags, email and SMS Subscriptions |
| SDK extension or embed | Mobile BI tools that wrap or coexist with the OneSignal SDK | Your wrapper sets External ID through the OneSignal SDK | Tags, custom events, messages |
Regardless of pattern, the OneSignal SDK is the source of truth for push and web Subscriptions when it is installed in the customer’s app. Server-side Subscription creation is intended for email and SMS only.
Common integration use cases
Pick the use cases relevant to your platform. Each links to the guide and API reference you need. Before writing any user data, review the Identity lifecycle.Create and identify users
OneSignal’s mobile and web SDKs create Users (with OneSignal IDs) and Subscriptions (with Subscription IDs) as end users interact with the customer’s app. Partner integrations can attach context to these Users by syncing the customer’s External ID and, optionally, custom aliases keyed off it.Users
How Users are created, stored, and identified by their External ID.
Subscriptions
How Subscriptions are created, stored, and marked as subscribed or unsubscribed.
Aliases
How custom aliases identify Users across platforms and devices.
Sync user attributes
Sync user properties (profile data, preferences, behavior) as Tags so customers can segment audiences and personalize messages.Tags
Add custom properties to Users for personalization and segmentation.
Update user API
Set tags and other properties on an existing User via the external_id or other alias.
Send custom events
Send important user actions to OneSignal to trigger Journeys in real time, or use them for delays, segmentation, and personalization.Custom events
Track User actions to trigger Journeys, personalization, and analytics.
Create custom events API
Send custom events to OneSignal programmatically.
Send messages
Send push, email, SMS, and Live Activities messages on behalf of mutual customers, directly from your platform. Useexternal_id or an alias_id to target individual users (for example, transactional messages), or use segments and filters to target groups. Always pass an idempotency_key and reuse it on retries to avoid duplicate sends.
Create message API
Send push, email, SMS, and Live Activities messages on behalf of mutual customers.
Live Activities
Push real-time updates on behalf of customers.
Manage templates
Sync and manage email, SMS/RCS, and push templates in OneSignal so customers can build campaigns directly from your platform.Templates
Learn about message templates.
Create template API
Create templates for push, email and SMS messages programmatically.
Capture event streams
Stream real-time engagement data (sends, clicks, opens, bounces, unsubscribes) from OneSignal to your warehouse for downstream analytics and automation.Event Streams
Stream real-time message events to your warehouse using the event names in this glossary.
Analytics overview
Measure message performance, user engagement, and conversions in OneSignal.
Embed OneSignal in your platform
Embed OneSignal with per-customer App IDs so customers can onboard without leaving your product.Apps and Organizations
Provision per-customer App IDs and manage many Apps under one Organization.
Developer hub
SDK setup, API reference, and the identity model used when integrating OneSignal.
Identity lifecycle
OneSignal’s identity model is sequenced. Calls made in the wrong order can attach data to anonymous users that cannot be merged with the identified user later, breaking multi-channel sync.The OneSignal SDK creates an anonymous user
When a customer’s app launches with the OneSignal SDK installed, the SDK creates an anonymous User with a OneSignal ID and a Subscription with a Subscription ID. At this point, no External ID is set.
The customer's app sets the External ID
When the customer’s app identifies the end user (for example, on login or signup), it should call
OneSignal.login(externalId). This promotes the anonymous user to an identified user. If a user with that External ID already exists, the current anonymous OneSignal ID is replaced by the existing user’s OneSignal ID, and the Subscription is reassigned to that user.This is the earliest point at which it is safe for a partner integration to attach data to that user.The partner integration writes user data
Once the External ID is set, your integration can safely:
- Attach aliases: Create or update alias
- Add tags: Update user
- Send custom events: Create custom events keyed by External ID
- Send messages: Create message with
include_aliases.external_id
- Correct: External ID set first
- Incorrect: Alias written first
- A user exists with Subscription ID:
SUB1, OneSignal ID:OSID1, and External ID:EIDA. - The user downloads the app on another device. The SDK creates a new anonymous User and a new Subscription with Subscription ID:
SUB2and OneSignal ID:OSID2. - The user logs into the app with
OneSignal.login("EIDA"). This identifies the anonymous user. OSID2is discarded andSUB2is moved toOSID1withEIDA.- User
OSID1withEIDAnow has 2 Subscriptions:SUB1andSUB2.
- The alias is bound to an anonymous, orphaned user that cannot be merged with the identified user later
- Subscriptions created under the alias get moved to a new OneSignal ID
- Messages targeted by your alias may fail to deliver
API endpoint reference
Use this matrix to map integration operations to the correct endpoint and its preconditions.| Operation | Endpoint | Precondition |
|---|---|---|
| Identify the user when the OneSignal SDK is installed | OneSignal.login(externalId) in the customer’s app | The customer’s app integrates the OneSignal SDK. |
| Create or upsert a user from a server-side integration (CDP-style) | POST /apps/{app_id}/users | Pass external_id in the request. Use this only when the OneSignal SDK is not installed in the customer’s app. |
| Add or update an alias on an existing user | PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity | External ID is set. |
| Update tags or other user properties | PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id} | External ID is set. |
| Add an email or SMS Subscription to a user | POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions | External ID is set. Push Subscriptions should be created by the SDK. |
| Send a message to one user | POST /notifications with include_aliases.external_id | External ID is set. Reuse idempotency_key on retries. |
| Send a message to a group | POST /notifications with included_segments or filters | None. |
| Record a custom event | POST /apps/{app_id}/custom_events | External ID is set. Reuse idempotency_key on retries. |
Verify your integration end-to-end
Before submitting your integration for partner verification, confirm each of the following on a test app:The end user appears with a non-anonymous External ID
In Audience > Users, find the test user and confirm their identity shows your customer’s External ID, not just an anonymous OneSignal ID.
Aliases attach to the identified user
Confirm any partner-specific aliases (for example,
integration_id) appear under the same User as the External ID, not under a separate anonymous user.Subscriptions link to one User
If the user has multiple channels (push, email, SMS), confirm all Subscriptions appear under one User. Multiple Users per person indicates an identity-sequencing issue. See Identity lifecycle.
Tags and properties write successfully
Confirm tags written by your integration appear on the User’s profile in the dashboard.
A test message reaches the test device
Send a test message using
include_aliases.external_id and confirm it delivers to the test user’s Subscription.Common integration mistakes
Avoid these patterns when building a OneSignal integration. Each one is a regression seen in real partner code. Writing aliases or tags before the External ID is set Aliases and tags attach to whichever User OneSignal can match (typically an anonymous one) and cannot be re-linked to the identified user later. Always require an External ID before writing identity data. See Identity lifecycle for the correct sequence. Treating the OneSignal ID as a stable customer identifier OneSignal IDs are internal and can change when users merge. Use the External ID as your stable cross-system identifier. Creating push Subscriptions server-side when the OneSignal SDK is installed The OneSignal SDK is the source of truth for push and web Subscriptions. Server-side Subscription creation is intended for email and SMS Subscriptions. Creating push Subscriptions via API when the SDK is installed produces duplicate or orphaned records. Writing the same field via both the SDK and the API Pick one writer per field. Concurrent writes from the SDK and a server-side integration create race conditions that overwrite each other unpredictably.FAQ
Is the OneSignal-Usage header required, or only recommended?
It is required for the partner program. Without the header, OneSignal cannot attribute API traffic to your integration, which blocks partner verification, usage reporting, and prioritized support.
Do I need a paid OneSignal plan to develop an integration?
No. You can build and test an integration on a free OneSignal account. Contactbd@onesignal.com if you need access to premium features for development or testing.
What’s the difference between using the OneSignal API and joining the partner program?
Any developer can call the OneSignal API. The partner program adds verified directory listing, co-marketing and co-selling opportunities, dedicated technical support, and progressively unlocked benefits as your integration grows. See Benefits of integrating with OneSignal.How long does partner verification take?
Verification timing depends on the complexity of your integration and the Partnerships team’s review queue. Submit the Partner Validation Request form when your integration is feature-complete. The Partnerships team responds in order of submission and the timeline depends on the complexity of the integration and the current review queue.Can I use one OneSignal app to serve multiple customers?
No. Each end customer should have their own OneSignal App ID so that data, subscriptions, and messages stay isolated. If you’re embedding OneSignal in your platform, see Apps and Organizations for how to provision per-customer App IDs under one Organization.Related pages
Partner integration user migration guide
Migrate an existing integration from the legacy Player API to the v2 User-based API.
Users
The identity model every partner integration depends on.
REST API overview
Authentication, retries, idempotency, and base URLs for all REST API calls.
Apps and Organizations
Provision per-customer App IDs and manage many Apps under one Organization.