This guide explains how to build a OneSignal integration, which APIs to use for common use cases, and how to verify your integration once it’s complete. Use this page if you’re embedding OneSignal into your platform, syncing user data, or triggering messages on behalf of mutual customers. Pay particular attention to the identity lifecycle — it determines whether your integration’s data attaches to the right user.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.
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 | The CDP carries a stable userId from upstream sources | Users, aliases, tags, email/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.
Trigger messages
Trigger 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.
Create message API
Send push, email, SMS, and Live Activities messages on behalf of mutual customers.
Live Activities
Push real-time Live Activity updates to iOS devices on behalf of mutual customers.
Manage templates
Sync and manage email, SMS/RCS, and push templates in OneSignal so customers can build campaigns directly from your platform.Templates
Create, manage, and use templates for push, email, SMS, and Live Activities messages.
Create template API
Create templates for push, email, SMS, and Live Activities 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.Platform embedding
Embed OneSignal directly within your platform, simplifying customer onboarding with unique App IDs.
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 that user already exists, the OneSignal ID is discarded and the existing OneSignal ID for that user is set.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 |
|---|---|---|
| Create or upsert a user with identity and properties | POST /apps/{app_id}/users | Set External ID via SDK first when the OneSignal SDK is installed |
| 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}/integrations/custom_events | External ID is set |
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.