The Targeted App Push API, also known as sending a push notification through the API, is a POST endpoint for delivering app push notifications directly to identified users by identifier, such as email, phone number, or UUID, rather than through a campaign segment. It supports rich media, deep links, carousel and slider advanced push types, and per-platform configuration for iOS and Android.
Use it for real-time, user-specific notifications such as order status updates from your backend system or price drop alerts on a user's wishlist item.
You can access analytics for targeted push notifications sent via this API through Reports > Mobile App Analytics > App Push API Campaigns on InOne.
Endpoint and Headers
Visit our Postman collection to test this request.
Header | Sample Value | Description |
|---|---|---|
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
Parameter | Description | Data Type | Required |
|---|---|---|---|
api_key | Your API key. Refer to API Authentication Tokens to get your API key. | String | Yes |
async | True: The request is queued and HTTP 202 {"message":"Async request accepted"} returns. The notification send results are not in the response. | Boolean | No |
notifications | The array of notification object that includes the push data | Array | Yes |
identifiers | The object that contains the unique identifier of the user. The key can be an identifier such as email, phone_number, or uuid. E.g., "phone_number": "+651234567890". | Object | Yes |
camp_id | ID of the campaign that can be used to retrieve the statistics of the push notification via Statistics API. You can set any campaign ID. | Integer | Yes |
camp_name | Name of the push notification | String | Yes |
title | Title of the push notification | String | Yes |
message | Content of the push notification | String | Yes |
image_url | URL of the image in rich push notifications | String | No |
GFC_enabled | When set to true, the Targeted Push API enforces your pushed global frequency cap (GFC). Each successful API push increments the user’s GFC counter by one. If the user has already reached the GFC limit, the API blocks the send. The user is excluded, no message is sent, and the count is not incremented. The default value is set to false. Even if GFC_enabled is set to false, the user's counter is still incremented. | Boolean | No |
ttl | Expiration time of the push notification in seconds | Integer | No |
android | Object for Android details | Object | No |
channel_id | ID of the channel | Integer | No |
ios | Object for iOS details | Object | No |
thread_id | ID of the notification thread | Integer | No |
deep_link | Key/value pairs to be passed to the application in the push payload. The most common use of deep links is sending the user to the selected landing page when they open the push notification. | Object | No |
sound | Name of the custom sound file in your app to play a custom sound | String | No |
badge | Badge for iOS | Integer | No |
content-available | (iOS only) true sends the notifications with content--available=1, but the notification does not appear. This can be used to execute background tasks remotely. | Boolean | No |
mutable-content | (iOS only) true sends the notification with mutable-content=1 and updates the current screen app pushes. This can be used to update app push notification content that was sent incorrectly on the user's screen. | Boolean |
|
The image_url is required for rich push notifications, but not for text-only push notifications.
To add key-value pairs to the deep_link object, you can use the following deep link keys depending on its type:
ins_dl_internal for an internal deep link,
ins_dl_external for an external deep link,
ins_dl_url_scheme for a URL scheme deep link,
ins_dl_json for a JSON deep link.
The URL in the value should always start with https://.
Sample Body
The sample body below is for sending a push notification with user-level reporting by providing an API key, a set of report attributes (such as email, phone number, device info, and app version), and notification details including identifiers, campaign info, title, message, image, time-to-live, opt-in checks, plus platform-specific settings for Android and iOS (e.g., sound, thread ID, badge, and deep links).
App push notifications are sent to a user's last active device.
camp_id allows you to list your app push notifications in the Message Center and get campaign-based reporting of your Push API campaigns. When replacing the sample values in the payload, make sure to use a unique campaign ID value in the camp_id key.
{
"api_key": "your_api_key_here",
"async": false,
"notifications": [
{
"identifiers": {
"INSIDER.uuid": "ios-user-uuid-12345",
"INSIDER.phone_number": "+65123456789",
"INSIDER.email": "iosuser@insiderone.com"
},
"camp_id": 1001,
"camp_name": "Campaign iOS",
"title": "Push notification for iOS user",
"message": "Hello, this is a push notification",
"image_url": "https://insiderone.com/image.jpg",
"ttl": 3600,
"ios": {
"deep_link": {
"screen": "product",
"product_id": "12345"
},
"mutable-content": true,
"content-available": true,
"thread-id": 1,
"badge": 1,
"sound": "default"
}
},
{
"identifiers": {
"INSIDER.uuid": "ios-user-uuid-12345",
"INSIDER.phone_number": "+65123456789",
"INSIDER.email": "iosuser@insiderone.com"
},
"camp_id": 1002,
"camp_name": "Campaign Android",
"title": "Push notification for Android user",
"message": "Hello, this is a notification",
"image_url": "https://insiderone.com/image.jpg",
"ttl": 3600,
"android": {
"deep_link": {
"screen": "product",
"product_id": "67890"
},
"sound": "default",
"channel_id": 1
}
}
]
}Add advanced_push_payload in notifications if you would like to use Advanced Pushes. The advanced_push_type value can be a carousel or slider. The following are the parameters of the advanced_push_payload.
Parameter | Definition | Data Type | Required |
|---|---|---|---|
advanced_push_type | Type of the advanced push: carousel or slider | String | Yes |
advanced_push_items | Details of the advanced push | Array | Yes |
image_url | URL of the image in rich push notifications | String | Yes |
deep_links | Key/value pairs to be passed to the application in the push payload. The most common use of deep links is sending the user to the selected landing page when they open the push notification. | Object | No |
description | Description for your push | String | Yes |
headline | Title for your push | String | Yes |
id | ID of your push | Integer | Yes |
For further details on advanced pushes, refer to Send advanced app pushes API.
{
"api_key": "Your API Key goes here",
"report_attributes": [
"INSIDER.carrier",
"INSIDER.idfa",
"INSIDER.name",
"INSIDER.surname",
"INSIDER.gender",
"INSIDER.age",
"INSIDER.birthday",
"INSIDER.email",
"INSIDER.phone_number",
"INSIDER.language",
"INSIDER.email_optin",
"INSIDER.sms_optin",
"INSIDER.push_optin",
"INSIDER.location_optin",
"INSIDER.insider_id",
"INSIDER.environment",
"INSIDER.idfa",
"INSIDER.device_token",
"INSIDER.udid",
"INSIDER.model",
"INSIDER.carrier",
"INSIDER.app_version",
"INSIDER.os_version",
"INSIDER.screen_width",
"INSIDER.screen_height",
"INSIDER.platform",
"INSIDER.timezone",
"INSIDER.device_language",
"INSIDER.sdk_version",
"INSIDER.last_ip",
"INSIDER.package_name"
],
"notifications": [
{
"identifiers": {
"INSIDER.email": "example@gmail.com",
"INSIDER.phone_number": "+9059713551597135123",
"INSIDER.uuid": "5971351231234567"
},
"advanced_push_payload": {
"advanced_push_type": "carousel",
"advanced_push_items": [
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value1"
},
"description": "Description for the item 1",
"headline": "Title for the item 1",
"id": 1
},
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value2"
},
"description": "Description for the item 2",
"headline": "Title for the item 2",
"id": 2
},
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value3"
},
"description": "Description for the item 3",
"headline": "Title for the item 3",
"id": 3
}
]
},
"camp_id": 1,
"camp_name": "Your push notification campaign name goes here",
"title": "Your push notification title goes here",
"message": "Your push content goes here",
"image_url": "https://your_image_url.jpg",
"ttl": 1,
"android": {
"channel_id": 1,
"sound": "sound_check",
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
},
"ios": {
"thread-id": 13,
"badge": 1,
"content-available": false,
"mutable-content": true,
"sound": "sound_check",
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
}
}
]
}You can replace the advanced_push_payload.advanced_push_items[n].deep_links.your_deeplink_key with a custom deep link key, or use one of the following default keys: ins_dl_internal, ins_dl_external, ins_dl_url_scheme, or ins_dl_json.
Sample Responses
200 OK
You will receive the following response if you send your request using the report_attributes array.
insider_id represents the profile ID in user profiles.
{
"successes": [
{
"INSIDER.age": null,
"INSIDER.app_version": "4.0",
"INSIDER.birthday": null,
"INSIDER.carrier": "mycarrier",
"INSIDER.device_language": "en",
"INSIDER.device_token": "d07951020f3835bbc303084ecda3746170cfb5d696ddcc55b6",
"INSIDER.email": "sample@mail.com",
"INSIDER.email_optin": null,
"INSIDER.environment": "production",
"INSIDER.gender": null,
"INSIDER.idfa": "AF3CCF3F-0V8E-6571-B296-E9BDFF7",
"INSIDER.insider_id": "940E4A98F309288AAC8C4",
"INSIDER.language": null,
"INSIDER.last_ip": null,
"INSIDER.location_optin": false,
"INSIDER.model": "iPhone 11",
"INSIDER.name": "John Smith",
"INSIDER.os_version": "14.7.1",
"INSIDER.package_name": "com.useinsider.iGurmeV3",
"INSIDER.phone_number": "+65123456789",
"INSIDER.platform": "iOS",
"INSIDER.push_optin": true,
"INSIDER.screen_height": null,
"INSIDER.screen_width": null,
"INSIDER.sdk_version": "10.6.0-RN-4.0.0",
"INSIDER.sms_optin": null,
"INSIDER.surname": null,
"INSIDER.timezone": "Europe/Helsinki",
"INSIDER.udid": "98BB170F5078F309288AAC8C4"
}
],
"errors": {}
}You will receive the following response if you send your request without the report_attributes array.
{
"successes": [
{
"INSIDER.device_token": "d07951020f3084ecd4d3deda3746170cfb5d69672c055b6"
}
],
"errors": {}
}There might be cases where the request returns a 200 response, but the app pushes cannot be sent to users. The following list displays the reasons for these cases.
noUserErr | "NoUserFound" |
optOutErr | "OptOut" |
unregisteredErr | "Unregistered" |
userGloballyCappedErr | "UserGloballyCapped" |
userGloballyCappedForInappErr | "UserGloballyCappedForInapp" |
invalidCertificateErr | "InvalidCertificate" |
400 Bad Request
The following response returns if your request is missing an identifier.
{
"error": "empty_insider_identifiers",
"message": "'insider_identifiers' object need to have at least one identifier"
}400 Bad Request
The following response returns if the notifications array is empty.
{
"error": "invalid_notifications",
"message": "'notifications' is empty, add some notification objects"
}400 Bad Request
The following response returns if the array has more than 20 objects.
{
"error": "invalid_notifications",
"message": "'notifications' can't have more than 20 objects"
}400 Bad Request
The following response returns if the deep link is blacklisted. The "aps" key cannot be used in the deep link. You need to remove the "aps" word from the deep link.
{
"error": "blacklisted_deeplink",
"message": "deepLink can't contain 'aps' key"
}400 Bad Request
The following response returns if the camp ID or channel ID is a negative integer.
{
"error": "negative_integer",
"message": "camp_id' and/or 'channel_id' must be greater than zero"
}400 Bad Request
The following response returns if the advanced push type is invalid.
{
"error": "invalid_advanced_push_type",
"message": "'advanced_push_type' must be either Carousel or Slider"
}400 Bad Request
The following response returns if the certificate is invalid. Refer to Push Certificates to see how to add push certificates for iOS, Android, and Huawei.
{
"error": "invalid_certificate",
"message": "You do not have a validated certificate. Please check Certificate section under Insider's Settings."
}401 Unauthorized
The following response returns if the API key is either empty or incorrect. Refer to API Authentication Tokens to get your API key.
{
"error": "bad_api_key",
"message": "'api_key' is either empty or wrong. You can get your API key from Insider Dashboard"
}Error reference
Use this table to identify and resolve the errors this endpoint returns. Each row shows the status code, the response body you receive, what causes it, and how to fix it.
Status | JSON response | Cause | Fix |
|---|---|---|---|
400 Bad Request | { "error": "empty_insider_identifiers", "message": "'insider_identifiers' object need to have at least one identifier" } | The insider_identifiers object is present but empty, so the request does not name a recipient. | Include at least one identifier, for example email, phone_number, or uuid. |
400 Bad Request | { "error": "invalid_notifications", "message": "'notifications' is empty, add some notification objects" } | The notifications array is empty. | Add at least one notification object to the array. |
400 Bad Request | { "error": "invalid_notifications", "message": "'notifications' can't have more than 20 objects" } | The notifications array holds more than 20 objects. | Send a maximum of 20 notification objects per request, and split larger sends across several requests. |
400 Bad Request | { "error": "blacklisted_deeplink", "message": "deepLink can't contain 'aps' key" } | The deep link contains the string aps, which is reserved by the Apple Push Notification service payload format. | Remove aps from the deep link. If the token is part of a query parameter or path segment, rename it. |
400 Bad Request | { "error": "negative_integer", "message": "camp_id' and/or 'channel_id' must be greater than zero" } | camp_id or channel_id is zero or negative. An uninitialized variable in the calling code is the usual reason. | Send positive integers for both values, taken from the campaign and channel records in your panel. |
400 Bad Request | { "error": "invalid_advanced_push_type", "message": "'advanced_push_type' must be either Carousel or Slider" } | advanced_push_type holds a value other than Carousel or Slider. The values are case sensitive. | Set advanced_push_type to Carousel or Slider, matching the capitalization exactly. |
400 Bad Request | { "error": "invalid_certificate", "message": "You do not have a validated certificate. Please check Certificate section under Insider's Settings." } | No validated push certificate exists for the target platform. The request is otherwise well formed, so this failure is configuration, not payload. | Add and validate the certificate for iOS, Android, or Huawei. See Push Certificates. |
401 Unauthorized | { "error": "bad_api_key", "message": "'api_key' is either empty or wrong. You can get your API key from Insider Dashboard" } | The API key is missing or incorrect. | Send a current API key from your panel. See API Authentication Tokens. |
429 Too Many Requests | No response body is published for this status code. | [VERIFY] You exceeded the rate limit of 10,000 requests per minute for this endpoint. Send Advanced App Pushes uses the same path with a separate limit of 1,000 requests per minute. | Throttle your client and retry with exponential backoff. Batch up to 20 notification objects per request to reduce request volume. |
Fail Records Messages
Message | Definition |
|---|---|
InvalidRegistration (Android) | Check the format of the registration passed to the server. Make sure it matches the registration token the client app receives from registering with FCM. Do not truncate or add additional characters. |
NotRegistered (Android) | The user uninstalled the app, and it is no longer reachable. |
MismatchSenderId (Android) | Google Sender ID used in the integration and the FCM Server Key do not belong to the same parent Google Account. |
BadDeviceToken (iOS) | The application and the app environment do not match. One is in development, and the other is in the production environment. |
DeviceTokenNotForTopic (iOS) | Push notification certificate topic and the application package name do not match. |
Unregistered (iOS) | The user uninstalled the app and is no longer reachable. |
Limitations
All functions must be executed with a simple HTTPS POST request.
The API key should be provided in the request body. If the key is incorrect, no operation will be executed.
The rate limit is 10000 requests per minute.
Each request can include up to 50 user identifiers, meaning the targeted push can be sent to up to 50 users.
You must complete the identifier integration with the Insider SDK's user object for your platforms. See Android, iOS, React Native, Flutter, and Cordova for further details.
The camp ID value should be greater than 0.
The preferred_type value can be slider or carousel.
The Android channel ID value should be greater than 0.
The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team. We can adjust it to fit your needs.