OneSignal Getting Started: Account Setup & First API Request (2026)

Getting started overview

Integrating OneSignal into an application requires a sequence of steps beginning with account creation and application setup within the OneSignal dashboard. This process yields the necessary API credentials, specifically the App ID and a REST API Key, which are fundamental for all subsequent programmatic interactions. Developers can then utilize these keys to send notifications via the OneSignal REST API or integrate one of the OneSignal SDKs for various platforms. The initial setup focuses on obtaining these keys and then executing a basic API call to confirm connectivity and functionality.

OneSignal supports multiple communication channels, including push notifications for web and mobile, in-app messaging, email, and SMS. The initial configuration typically involves selecting the primary channel for development and then configuring platform-specific settings, such as obtaining Google Firebase Cloud Messaging (FCM) server keys for Android push notifications or an Apple Push Notification service (APNs) authentication key for iOS. These platform-specific credentials link the OneSignal service to the respective notification infrastructure provided by Google and Apple.

The developer experience with OneSignal is designed to provide clear documentation and a wide range of SDKs, simplifying the process of integrating notification capabilities into diverse applications. The platform's API reference details all available endpoints for programmatic interaction, allowing for fine-grained control over notification delivery, audience segmentation, and analytics retrieval. A successful first request validates the API key setup and demonstrates the ability to send a basic notification, serving as a foundation for more complex engagement strategies.

The following table outlines the foundational steps for getting started with OneSignal:

Create an account and get keys

To begin using OneSignal, navigate to the OneSignal pricing page to sign up for a free account. The free tier supports up to 10,000 subscribers and 50,000 pushes per month, which is suitable for initial development and testing. After creating your account, you will be prompted to create your first application or website. This application represents the specific platform (e.g., an iOS app, an Android app, or a web application) that will send and receive notifications through OneSignal.

During the application setup, you will define the primary platform for your notifications. For mobile applications, this typically involves configuring the appropriate push notification services. For Android, this means integrating with Firebase Cloud Messaging (FCM). You will need to create a Firebase project, enable Cloud Messaging, and then obtain the Server Key and Sender ID from your Firebase project settings. These credentials are then entered into the OneSignal dashboard under your app's settings. Similarly, for iOS, you will generate an APNs authentication key or a certificate from your Apple Developer account and upload it to OneSignal. This step is crucial for OneSignal to securely communicate with Apple's push notification infrastructure.

Once your application is configured, you can retrieve your essential API keys. From the OneSignal dashboard, navigate to Settings > Keys & IDs. Here, you will find:

• OneSignal App ID: A unique identifier for your application, essential for SDK initialization and API calls.
• REST API Key: A secret key used to authenticate your API requests to OneSignal. This key should be kept confidential and never exposed in client-side code.

These two keys are the primary credentials required for making programmatic requests to the OneSignal API. For client-side SDK integration, only the App ID is typically required, as the SDK handles user registration and notification receipt. The REST API Key is exclusively for server-side operations, such as sending notifications or managing user data.

Your first request

After obtaining your OneSignal App ID and REST API Key, you can proceed with making your first API request. This initial request typically involves sending a test push notification to a subscribed device or web browser. Before sending a notification, you need at least one device or browser subscribed to receive notifications from your OneSignal application. This is usually achieved by integrating the OneSignal SDK into your client application and having a user opt-in to notifications.

For demonstration purposes, let's consider sending a basic push notification to all subscribed users using the OneSignal REST API. The API endpoint for sending notifications is https://onesignal.com/api/v1/notifications. You will make a POST request to this endpoint with a JSON payload containing the notification details and your authentication header.

Here's an example using curl, a common command-line tool for making HTTP requests:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YOUR_REST_API_KEY" \
     --data-binary "{
       \"app_id\": \"YOUR_APP_ID\",
       \"included_segments\": [\"All\"],
       \"contents\": {\"en\": \"Hello World! This is your first OneSignal push.\"}
     }" \
     https://onesignal.com/api/v1/notifications

Replace YOUR_REST_API_KEY with your actual REST API Key and YOUR_APP_ID with your OneSignal App ID. The included_segments: ["All"] parameter targets all users subscribed to your application. The contents object specifies the notification message, with en indicating the English language content. Upon a successful request, the API will return a JSON response indicating the notification ID and its status.

If you are integrating an SDK, the process for sending a notification from your server-side code will be similar, utilizing the same API endpoint and authentication. For client-side SDK integration, after initialization with your App ID, the SDK handles user registration and receipt of notifications automatically. For example, in a web application, you would initialize the SDK:

window.OneSignal = window.OneSignal || [];
OneSignal.push(function() {
    OneSignal.init({
        appId: "YOUR_APP_ID",
    });
});

After this initialization, if the user grants notification permissions, their device will be registered with OneSignal and become eligible to receive push notifications. This client-side setup is critical before you can successfully send a notification via the REST API to an actual device.

Common next steps

After successfully sending your first notification, several common next steps can enhance your OneSignal integration:

• Audience Segmentation: OneSignal allows you to segment your users based on various criteria such as tags, user properties, and location. This enables targeted notification delivery, which can significantly improve engagement. Explore the OneSignal documentation on segmentation to define custom segments relevant to your application's user base.
• Advanced Notification Features: Experiment with advanced notification features like action buttons, rich media (images, videos), and notification categories. These features can make your notifications more interactive and informative.
• In-App Messaging: Beyond push notifications, OneSignal offers in-app messaging, which allows you to display messages to users while they are actively using your application. This is useful for onboarding flows, feature announcements, or important updates. The in-app messages guide provides details on implementation.
• Email and SMS Integration: If your communication strategy extends to email and SMS, configure these channels within OneSignal. This allows for a unified multi-channel messaging approach, managing all communications from a single platform.
• Webhooks and Integrations: Set up webhooks to receive real-time data about notification deliveries, opens, and other events. OneSignal also integrates with various analytics and CRM platforms, allowing you to sync user data and campaign performance.
• A/B Testing: Utilize OneSignal's A/B testing capabilities to optimize your notification content and timing. This helps in understanding what resonates best with your audience and improves overall campaign effectiveness.
• Error Handling and Analytics: Implement robust error handling for your API calls and monitor notification delivery and engagement through the OneSignal dashboard analytics. This provides insights into user behavior and helps in refining your messaging strategy.

Troubleshooting the first call

When making your first API call to OneSignal, several common issues can arise. Understanding these can help in quickly diagnosing and resolving problems:

• Incorrect API Keys: Double-check that you are using the correct OneSignal App ID and REST API Key. The REST API Key is case-sensitive and must be included in the Authorization: Basic header. An incorrect key will typically result in an HTTP 401 Unauthorized error. Ensure no leading or trailing spaces are present in the key.
• Invalid JSON Payload: The data sent in the --data-binary part of your curl request must be valid JSON. Syntax errors, missing commas, or unescaped quotes can cause the API to reject the request, often returning an HTTP 400 Bad Request error. Use a JSON linter to validate your payload before sending.
• No Subscribed Users: If your notification appears to send successfully but no one receives it, verify that you have at least one device or browser subscribed to your OneSignal application. Notifications can only be delivered to registered users. Check the OneSignal dashboard under Audience > All Users to confirm active subscriptions.
• Platform-Specific Configuration Issues: For mobile push notifications, ensure that your Firebase Cloud Messaging (FCM) server key (for Android) or Apple Push Notification service (APNs) authentication key/certificate (for iOS) is correctly configured in your OneSignal app settings. Mismatches or expired credentials will prevent notifications from reaching devices. Refer to the Firebase FCM setup guide or the iOS push certificate generation guide for detailed steps.
• Firewall or Network Restrictions: In some development environments, network firewalls or proxy settings might block outgoing POST requests to onesignal.com. Ensure that your environment allows outbound connections to the OneSignal API endpoints.
• Rate Limiting: While unlikely for a first call, be aware that OneSignal has API rate limits. Exceeding these limits will result in HTTP 429 Too Many Requests errors. For initial testing, this is generally not a concern.
• SDK Initialization Errors: If you are relying on an SDK to register users, ensure that the SDK is correctly initialized with the App ID and that the user has granted notification permissions. Console logs in the browser or device logs in mobile development environments can provide clues to SDK-related issues.