OneSignal
Sync user data and tags to OneSignal for push notifications, email, SMS, and in-app messaging. Zeotap keeps your OneSignal user profiles and tag-based segments in sync with your warehouse data.
Prerequisites
- A OneSignal account with an active app
- A OneSignal REST API Key (found in Settings > Keys & IDs)
- Your OneSignal App ID (UUID format, found in Settings > Keys & IDs)
Authentication
OneSignal uses REST API Key authentication.
- In OneSignal, go to Settings > Keys & IDs
- Copy your REST API Key
- Paste it into the REST API Key field in Zeotap
- Copy the OneSignal App ID and paste it into the App ID configuration field
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| App ID | Text | Yes | Your OneSignal application ID (UUID format). Found in Settings > Keys & IDs. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Object Type | Select | Yes | The type of data to sync. Options: User Tags (default), Create/Update Users. |
| Alias Label | Select | Yes | The alias type used to identify users. Options: External ID (default), OneSignal ID. Only shown when Object Type is User Tags. |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Upsert | Yes |
| Insert | — |
| Update | Yes |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
| Upsert | Yes |
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| external_id | Primary user identifier for OneSignal |
Default Destination Fields
external_id, language, timezone_id, country, lat, long, first_active, last_active
How It Works
User Tags (Default)
When the object type is User Tags, Zeotap updates tags on existing OneSignal users. Tags are key-value string pairs attached to user profiles. OneSignal segments are filter-based and automatically include or exclude users based on their tags.
For each row in the sync:
- Zeotap sends a
PATCHrequest to/apps/{app_id}/users/by/{alias_label}/{alias_id} - Mapped fields matching known OneSignal properties (language, timezone_id, country, etc.) are sent as user properties
- All other mapped fields are sent as tags
Create/Update Users
When the object type is Create/Update Users, Zeotap creates new users or merges data into existing users. The OneSignal Create User endpoint is idempotent: if a user with the given external_id already exists, their properties are merged.
Audience Syncs
OneSignal segments are filter-based — users automatically enter or leave segments based on their tag values. Zeotap manages audience membership by setting and clearing tags:
- Add / Upsert: Sets a tag on the user (e.g.,
audience_name: "true") - Remove: Clears the tag by setting it to an empty string
- Mirror: Sets tags for added/changed rows, clears tags for removed rows
To use audience syncs, create a OneSignal segment with a User Tag filter matching the tag name used in your sync.
Rate Limits
OneSignal enforces the following rate limits:
| Endpoint | Rate Limit |
|---|---|
| User/Subscription Management | 1,000 requests/sec/app |
| Per-user updates | 1 request/sec/user |
Zeotap automatically retries requests that receive HTTP 429 responses, respecting the Retry-After header returned by OneSignal.
Best Practices
- Use External ID as the alias: Map a stable, unique identifier from your warehouse to
external_idfor consistent user matching. - Keep tags as strings: OneSignal tags are string key-value pairs. Non-string values are automatically converted.
- Create segments in OneSignal first: Before running audience syncs, create a segment in OneSignal with a User Tag filter matching your audience tag name.
- Batch size considerations: The OneSignal User API is per-user (no batch endpoint), so large syncs may take longer compared to batch-capable destinations. Zeotap handles this automatically with retry and rate limit awareness.
- Monitor rate limits: For apps with many users, consider scheduling syncs during off-peak hours to avoid rate limit contention with your application’s real-time API calls.
Troubleshooting
Authentication failed: invalid REST API key or App ID
Verify that you are using the REST API Key (not the User Auth Key or Safari Web ID). The REST API Key is found in OneSignal under Settings > Keys & IDs.
User not found (404)
When using the User Tags object type, the user must already exist in OneSignal. If you need to create users, switch to the Create/Update Users object type.
Tags not appearing on users
Ensure that the mapped fields are not OneSignal reserved property names (language, timezone_id, country, lat, long, first_active, last_active). These are sent as user properties, not tags.
Segment not updating after sync
OneSignal segments are filter-based and update asynchronously. After syncing tags, it may take a few minutes for segment membership to reflect the changes. Verify that your segment filter matches the exact tag key being synced.
Rate limit errors (429)
If you see frequent 429 errors, your sync volume may be exceeding OneSignal’s rate limits (1,000 requests/sec/app or 1 request/sec/user). Consider reducing sync frequency or splitting large audiences into smaller batches.
Missing external_id mapping
The external_id field is required for all sync operations. Ensure you have mapped a source column to the external_id destination field in your field mapping configuration.