Send Targeted App Pushes

You can use the Targeted Push API in various cases, such as sending status updates on an order from your ecommerce platform or informing users of a sale on an item on their wishlist.

You can reach the analytics of your targeted push notifications sent via this API through Reports & Analysis > Mobile App Analytics > Push API Campaigns on Inone.

Endpoint and Headers

POST https://mobile.useinsider.com/api/v2/notification/user

Visit our Postman collection to test this request.

Headers

Header	Sample Value	Description
Content-Type	application/json	This header specifies the media type of the resource.

Body Parameters

Parameter	Description	Data Type	Required
headline	Title of the advanced push item	String	Yes
description	Description of the advanced push item	String	Yes
api_key	Your API key. Refer to API Authentication Tokens to get your API key.	String	Yes
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	Yes
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. In this case, the GFC is not checked for the request, and the user's counter is not incremented even if the push is sent successfully.	Boolean	No
ttl	Expiration time of the push notification in seconds	Integer	No
check_optin	true shows the opt-in delivery count information in the API response. false does not show the count.	Boolean	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	No

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.

Your title goes here

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 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": "sample@mail.com",
                "INSIDER.phone_number": "+65123456789",
                "INSIDER.uuid": "1234567890"
            },
            "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,
            "check_optin": true,
            "android": {
                "channel_id": 1,
                "sound": "sound_check",
                "deep_link": {
                    "ins_dl_internal": "https://www.deeplink.useinsider"
                }
            },
            "ios": {
                "thread-id": 1,
                "badge": 1,
                "content-available": false,
                "mutable-content": true,
                "sound": "sound_check",
                "deep_link": {
                    "ins_dl_internal": "https://www.deeplink.useinsider"
                }
            }
        }
    ]
}

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,
            "send_single_user": true,
            "check_optin": true,
            "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"
                }
            }
        }
    ]
}

Your title goes here

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.

Your title goes here

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.

{
  "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"
}

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 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 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.