Documentation > API

Working with Notifications API

Create Push Notification Campaigns based on Events/User Properties

Segment your users and send them push notifications using the below documented API request

Endpoint

A request to send push notifications is an HTTP URL of the following form:

POST https://api.clevertap.com/1/targets/create.json

Authentication

All requests should include your CleverTap Account ID and CleverTap Account Passcode in the request headers keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode , respectively.
Content-Type header must be specified as application/json.

Payload

JSON formatted payload with the following keys:

Required parameters

name – The name of your campaign which will reflect in your CleverTap dashboard

title – Title content of your push notification message which is sent to the user

body – Body content of your push notification message which is sent to the user

devices – Inputs must be an array, the valid inputs here are; android, ios, windows

when – This key entails when you want to send out push notifications, valid inputs are now (to send the notification right away) or YYYYMMDD HH:MM to schedule the notification for a particular date and time

where – Allows filtering of target base by user properties and actions. Send empty object ({}) to target entire user base.

This endpoint is throttled to 1 request per second. If you wish to send notifications based on user identity, please check the push to user profiles endpoint

Optional parameters

event_name – Allows you to target users based on an event they have performed. Present within where clause

from & to – Date range within which users should have performed the event you have specified in event_name, input values have to be formatted as integer YYYYMMDD. Present within where clause

Refer here for documentation on advanced queries, their structure, and examples.

Notification Sent event is supported here. Further information about the event is available in the special events section on the above link.

estimate_only – if this is set to true the request will return an estimated reach of the campaign i.e the number of users who will get the notification when you send it out

Setting estimate_only to true will only estimate (and not create) the campaign

Add "mutable-content": "true" in platform_specific: ios to trigger your iOS 10 Notification Service and/or Content App Extensions.

Example payload

{
    "name": "My API Campaign",
    "estimate_only": true,
    "where": {
        "event_name": "App Launched",
        "from": 20150101,
        "to": 20150303,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "Key": "Customer Type",
                    "value": "Platinum"
                }
            ]
        }
    },
    "content": {
        "title": "Hi!",
        "body": "How are you doing today?",
        "platform_specific": {
            "windows": {
                "deep_link": "example.com",
                "Key": "Value_windows"
            },
            "ios": {
                "mutable-content": "true", 
                "deep_link": "example.com",
                "sound_file": "example.caf",
                "category": "application category//Books",
                "badge_count": 1,
                "Key": "Value_ios"
            },
            "android": {
                "background_image": "http://example.jpg",
                "default_sound": true,
                "deep_link": "example.com",
                "large_icon": "http://example.png",
                "Key": "Value_android"
            }
        }
    },
    "devices": [
        "android",
        "ios",
        "windows"
    ],
    "when": "now"
}
copy Copied

Response

{
    "status": "success",
    "id": 1457433898,
    "estimates": {
        "android": 10,
        "ios": 30,
        "windows": 5
    }
}
copy Copied

HTTP Response Codes

200 Successful request
400 Bad Request. Some mandatory parameter was missing
429 Too many requests were made concurrently.
500 Server Error
Currently, we return HTTP error code: 429 when you make more than 3 concurrent requests. Please try again after 10 minutes

Send Notifications based on User Identity

Using this API, as listed below you can send notifications to your users based on their Facebook ID, Google Plus ID, Email ID, Identity or CleverTap ID.

Authentication

All requests should include your CleverTap Account ID and CleverTap Account Passcode in the request headers keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode , respectively.
Content-Type header must be specified as application/json.

Endpoint

The endpoint to send notifications to individual users is hosted at

Select Platform
POST https://api.clevertap.com/1/send/push.json
copy Copied
POST https://api.clevertap.com/1/send/email.json
copy Copied

Payload

JSON formatted payload with the following keys:

Required parameters

FBID, GPID, Email, Identity, objectid– You can use one more of these identifiers to target your users (array list of upto a 1000 entries)

Tag Groups

tag_group – Each message can be tagged into a tag group, and the stats (sent/viewed/clicked/converted) will be shown against each tag group in the CleverTap dashboard
You can create at most 20 tags

If not specified, the stats will be shown against “Not Tagged”.

Optional parameters

respect_frequency_caps – Specify false, if you don’t want the notification to honor frequency caps.
respect_frequency_caps field defaults to true

platform_specific – You can set key-value pairs, image links and deep links for specific platforms, acceptable platforms are android, ios, windows.

Example payload

Select Platform
{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
        "GPID": [
            "1928288389299292"
        ],
        "Email": [
            "john@doe.com",
            "jane@doe.com"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
    "respect_frequency_caps": false,
    "content": {
        "title": "Welcome",
        "body": "Hello world!",
        "platform_specific": {
            "windows": {
                "deep_link": "example.com",
                "key": "value_windows"
            },
            "ios": {
                "deep_link": "example.com",
                "sound_file": "example.caf",
                "category": "notification category",
                "badge_count": 1,
                "key": "value_ios"
            },
            "android": {
                "background_image": "http://example.jpg",
                "default_sound": true,
                "deep_link": "example.com",
                "large_icon": "http://example.png",
                "key": "value_android"
            }
        }
    }
}
copy Copied
{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
        "GPID": [
            "1928288389299292"
        ],
        "Email": [
            "john@doe.com",
            "jane@doe.com"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
    "respect_frequency_caps": false,
    "content": {
        "subject": "Welcome",
        "body": "<div>Your HTML content for the email</div>"
    }
}
copy Copied

Responses

Success

{
    "status": "success",
    "message": "Added to queue for processing"
}
copy Copied

A success response implies payload validity and addition to processing queue. Message delivery is handled by the provider (push or email) and is subject to valid recipient ID

Fail

{
    "status": "fail",
    "error": "<error message here>",
    "code": <error code here>
}
copy Copied
Error codes

21 – to is a mandatory field
84 – Invalid recipients”
73 – “respect_frequency_caps” must be a Boolean
78 – Invalid JSON payload
89 – Unexpected error, please try again

This API supports up to 1000 requests per second. To bypass the limit, please batch your requests. Up to 1000 users can be specified in each request.

HTTP Response Codes

200 Successful request
400 Bad Request. Some mandatory parameter was missing
500 Server Error

Stop Scheduled API Campaigns

Campaigns scheduled using the API can be stopped using the below documented API request

Endpoint

A stop schedule campaign request is an HTTP URL of the following form:

POST https://api.clevertap.com/1/targets/stop.json

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request headers keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.

Payload

JSON formatted request which has to have the following key:

id – CleverTap ID of the scheduled campaign which you want to stop, you can find this id in your CleverTap dashboard under the push section.

Example Request

{
    "id": 1457432766
}
copy Copied

Response

{
    "status": "success"
}
copy Copied

View Statistics of Push Campaigns

You can retrieve campaign statistics using the below documented API request.

Endpoint:

A view statistics request is an HTTP URL of the following form :

POST https://api.clevertap.com/1/targets/result.json

Authentication

All requests should include your CleverTap Account ID and CleverTap Account Passcode in the request headers
keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode respectively.

Payload

JSON formatted payload has to have the following key:
id – CleverTap Campaign ID of the campaign whose statistics you want to view, you can find this ID in your CleverTap dashboard under the Push section

Example Payload

{
    "id": 1457432766
}
copy Copied

Response

{
    "result": {
        "clicked": 28,
        "sent": 82
    },
    "status": "success"
}
copy Copied

Errors

If the campaign whose id you have specified has not been completed, you can expect the following response:

{
    "error": "This target hasn't been completed",
    "status": "fail"
}

copy Copied