Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

Application identifier

Please refer to the API Apps list section to get the App identifier.

Transactional endpoint update

The transactional endpoint /api/transac_push and the use of paramVars are deprecated, but will continue to work for the previously launched campaigns. Please refer to the section below to get the details about the new endpoint and new options you have for transactional campaigns.

Updated on September 5th, 2017

List all campaigns

GET /api/campaigns?limit=limit&offset=offset&order=order

Query parameters

Property Type Discussion Default
limit integer Maximum number of campaigns to return -
offset integer Offset in number of items to navigate through the results 0
order string Campaigns are ordered by date, descending.
You can add a first ordering by passing one of status, app, type
-

Response

Status: 200 OK

{
    "limit": "3",
    "offset": "0",
    "result": [
        {
            "app_id": "FAAPPLI_0VDvT50",
            "end_date": 1461830400,
            "from_crm": false,
            "identifier": "FACMPGN_GPZIBgqJd1ofdDde",
            "includes_inapp": false,
            "includes_push": true,
            "name": "With DLP",
            "params": {
                "push_includes_sound": true,
                "push_message": "The message",
                "push_parameters": [
                    {
                        "key": "a key",
                        "value": "the value"
                    },
                    {
                        "key": "another key",
                        "value": "another value"
                    }
                ]
            },
            "reach": {
                "inapp": {
                    "percentage": 0.0,
                    "segment_size": 0
                },
                "push": {
                    "percentage": 0.7143,
                    "segment_size": 5
                }
            },
            "start_date": 1461743080,
            "stats": {
                "total_push_openings": 0,
                "total_push_sent": 2
            },
            "status": "Ongoing",
            "type": "classic",
            "updated_at": 1461743098,
            "variants": [
                {
                    "id": 11,
                    "name": "default variant",
                    "default": true,
                    "params": {
                        "push_includes_sound": true,
                        "push_message": "The message",
                        "push_parameters": [
                            {
                                "key": "a key",
                                "value": "the value"
                            },
                            {
                                "key": "another key",
                                "value": "another value"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "app_id": "FAAPPLI_0VDvT50",
            "end_date": 1461772800,
            "from_crm": false,
            "identifier": "FACMPGN_A0_VTzjxCWE-m2Yt",
            "includes_inapp": false,
            "includes_push": true,
            "name": "sdf",
            "params": {
                "push_includes_sound": true,
                "push_message": "cvbncvbn"
            },
            "reach": {
                "inapp": {
                    "percentage": 0.0,
                    "segment_size": 0
                },
                "push": {
                    "percentage": 0.4286,
                    "segment_size": 3
                }
            },
            "start_date": 1461685458,
            "stats": {
                "total_push_openings": 0,
                "total_push_sent": 1
            },
            "status": "Ongoing",
            "type": "classic",
            "updated_at": 1461685463,
            "variants": [
                {
                    "id": 12,
                    "name": "default variant",
                    "default": true,
                    "params": {
                        "push_includes_sound": true,
                        "push_message": "cvbncvbn"
                    }
                }
            ]
        },
        {
            "app_id": "FAAPPLI_0VDvT50",
            "end_date": 1461790800,
            "from_crm": false,
            "identifier": "FACMPGN_BqCoPgLQjo8VQKZy",
            "includes_inapp": false,
            "includes_push": true,
            "name": "manual segment",
            "params": {
                "push_includes_sound": true,
                "push_message": "My segmented message"
            },
            "reach": {
                "inapp": {
                    "percentage": 0.0,
                    "segment_size": 0
                },
                "push": {
                    "percentage": 0.7143,
                    "segment_size": 5
                }
            },
            "start_date": 1461771000,
            "stats": {},
            "status": "Scheduled",
            "type": "classic",
            "updated_at": 1461684293,
            "variants": [
                {
                    "id": 13,
                    "name": "default variant",
                    "default": true,
                    "params": {
                        "push_includes_sound": true,
                        "push_message": "My segmented message"
                    }
                }
            ]
        }
    ],
    "success": true,
    "total_count": 768
}

Campaign creation

POST /api/campaign

This section will explain how to create classic and transactionnal campaigns.

Body parameters

Property Type Description Default
name string A name for your campaign, never displayed to your customers required
type string Campaign type. classic or transactional required
source string Please pass API required
app_id string The application identifier targeted by this campaign required
includes_push boolean If true, the campaign will send a push notification. required
includes_inapp boolean If true, the campaign will send an in-app notification. required
start_date timestamp Start of the campaign, in seconds since epoch. required
end_date timestamp End of the campaign, in seconds since epoch required
cmp_action string If send, the campaign will be scheduled for start_date and eventually immediately sent.
If save, this campaign will be a Draft and won't be scheduled.
required
params object Object with details on the campaign payload. Will be detailed in the examples below required

Minimal classic push campaign

To create a push notification campaign, you need to set these fields:

Example

{
    "app_id": "FAAPPLI_0VDvT50",
    "cmp_action": "send",
    "end_date": 1461679200,
    "includes_inapp": false,
    "includes_push": true,
    "name": "Most simple classic push only",
    "params": {
        "push_message": "The push message your customers will see."
    },
    "source": "API",
    "start_date": 1461616200,
    "type": "classic"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_vRvb98ysXme2IeHj"
    },
    "success": true
}

Minimal classic in-app campaign

To create an in-app campaign, you need to set these fields:

Example

{
    "app_id": "FAAPPLI_0VDvT50",
    "cmp_action": "send",
    "end_date": 1461679200,
    "includes_inapp": true,
    "includes_push": false,
    "name": "Most simple classic push only",
    "params": {
        "message_title": "inapp title",
        "message_content": "inapp body content",
        "message_btn": "label for the default inapp button"
    },
    "source": "API",
    "start_date": 1461616200,
    "type": "classic"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_SMdP2t1AjrFPGUfa"
    },
    "success": true
}

Push and in-app classic campaign

To create a campaign with both push and in-app notifications, you need to set these fields:

Example

{
    "app_id": "FAAPPLI_0VDvT50",
    "cmp_action": "send",
    "end_date": 1461679200,
    "includes_inapp": true,
    "includes_push": true,
    "name": "Most simple classic push only",
    "params": {
        "push_message": "The push message your customers will see.",
        "message_title": "inapp title",
        "message_content": "inapp body content",
        "message_btn": "label for the default inapp button"
    },
    "source": "API",
    "start_date": 1461616200,
    "type": "classic"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_bo1BXXbrx0-dNy9V"
    },
    "success": true
}

Classic campaign with audience targeting using segments

Using segmentation lets you target specific population of your application audience. It's recommanded to set up your segment in our web interface before using them with the API, this way you can anticipate your campaign reach levels.

Your campaign payload will need to add the filters[blocks[filters]] key, which require these fields:

Example

{
    "app_id": "FAAPPLI_0VDvT50",
    "cmp_action": "send",
    "end_date": 1461679200,
    "includes_inapp": false,
    "includes_push": true,
    "name": "Most simple classic push only",
    "params": {
        "push_message": "The push message your customers will see."
    },
    "filters": {
        "blocks": [
          {
            "filters": [
              {
                "filter_on": "segments",
                "selection": "any_of",
                "segment_identifiers": ["FASEGMT_uWQ4x3fPuNMt2PjC"],
                "operator": "is_in"
              }
            ]
          }
        ]
      },
      "source": "API",
      "start_date": 1461616200,
      "type": "classic"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_pqQA34xyA-opMiFs"
    },
    "success": true
}

Classic campaign with deeplinking

When scheduling a push notification, you can pass arbitrary variables so your application can react specificaly to them, most often by loading a specific page. You achieve that by passing an array of objects with two attributes: key and value.

{
    ...
    "push_parameters": [
        {
            "key": "a key",
            "value": "the value"
        },
        {
            "key": "another key",
            "value": "another value"
        }
    ]
}

Example

{
    "app_id": "FAAPPLI_0VDvT50",
    "cmp_action": "send",
    "end_date": 1461679200,
    "includes_inapp": false,
    "includes_push": true,
    "name": "Most simple classic push only",
    "params": {
        "push_message": "The push message your customers will see.",
        "push_parameters": [
            {
                "key": "a key",
                "value": "the value"
            },
            {
                "key": "another key",
                "value": "another value"
            }
        ]
    },
    "source": "API",
    "start_date": 1461616200,
    "type": "classic"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_68XnfPJPb86gfTP5"
    },
    "success": true
}

Transactional campaign

Transactional campaigns can contain variable placeholders in their message. These placeholders are defined by a special syntax, starting with *@ and ending with its symetric @*. For example, *@this_is_a_valid_placeholder@*.

Transactional template_variable

The declaration of params[template_variables] array is not supported anymore, now all the varaible are set in the fields and only in the fields, using the special syntax described above.

The response will contain the campaign_id value. campaign_id can although be found later in the url of the campaign's result page. You can use this value to trigger transanctional campaigns from your system as long as the campaign is still running. Please refer to the Sending transactional campaign messages section for more details on sending transactional campaign messages.

Example

{
    "name": "Simple transac",
    "type": "transactional",
    "source": "API",
    "variants":[
        {
            "name": "Variant A",
            "params": {
                "push_message": "Hello *@first_name@* *@last_name@*, we hope you a nice day",
                "push_title":"Welcome  *@first_name@*"
            }
        }
     ],
    "app_id": "FAAPPLI_0VDvT50",
    "includes_push": true,
    "includes_inapp": false,
    "start_date": "now",
    "cmp_action": "send"
}

Response

Status: 200 OK

{
    "result": {
        "campaign_api_identifier": "CGN_FOLLOWANALYTICSTEST_1461745425869",
        "campaign_id": "FACMPGN_VCFzh_NpR3Qrru3B"
    },
    "success": true
}

Transactional Push and In-App messages

Set of APIs to send messages to specified User Ids and retrieve reports on sendings and hits.

Send a batch of transactional messages

POST /api/transac

Body parameters

Property Type Description Default
campaignKey array of strings The campaign unique key to identify which campaigns needs to be used for sending the messages. campaign_id should be used here required
sendAt date A date when the sending should occur, expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -
messages array of objects The parameters of the messages to send to the app’s users required
message[user] string The userId to whom the message must be sent required
message[templateVars] object Variables used in the message template. Key is the variable key, value is the value to assign to it for this user. -

Example

{
    "campaignKey":["FACMPGN_fQq2YaB9vrJQuDid"],
    "messages":[
        {
            "user":"john365",
            "templateVars":{"lastname":"Doe","firstname":"John", "contractNumber":"ABC56"}
        },
        {
            "user":"duce23",
            "templateVars":{"lastname":"Duce","firstname":"JC", "contractNumber":"234AE"}
        }
    ]
}

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "requestId": "A_UNIQUE_REQUEST_ID"
    }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Invalid Resquest, missing or invalid parameters,..."
}

Status: 404

{
    "status": "404",
    "success": false,
    "error_message": "Unknown campaign key at index ..."
}

Status: 405

{
    "status": "405",
    "success": false,
    "error_message": "Campaign not ready at index..."
}

Retrieve a sending report

API to generate a status report of the messages sent. Only the last 30 days of data are available.

GET /api/transac/campaignKey/reports?requestId=requestId&page=page&page_size=page_size

Query parameters

Property Type Description Default
campaignKey array of strings The campaign unique key to identify which campaign needs to be launched. campaign_id should be used here required
requestId string The requestId retrieved from transactional message send API result. -
page integer The page of hits report to retrieve. Negative values causes a 400 error. 1
page_size integer The number of hits to retrieve per page.
Range of values is [1..5000]. Values outside range cause a 400 error.
5000

Response

The key that you'll want to interpret is result[reports[campaignStatus]], that's an array of objects, one per targeted user device.

Each hash contains those keys:

Property Type Description
user string The original user identifier given when sending the message
device_id string Device identifier indicating where the message was delivered. A user can be seen multiple times if logged on multiple devices.
date date Date of sending attempt
code string The status code of the attempt. See list below.
details string Human readable details on the sending attempt

Possible error codes are:

Error code Description
OPT_OUT The user refuses to receive this application pushes
MESSAGE_TO_BIG The message was rejected per GCM (Android) or APNS (Apple) because it was too long
MISSING_TEMPLATE_PARAMS One or more placeholder contained in any fields of the campaign message is missing into the messages[templateVars] Array when you sent the request.
NOT_ON_LAST_LOGIN another user than the one targeted has logged since the targeted user
NO_DEVICE_FOR_USER the targeted user never connected to that application, so we can't determine a device to target
CANCELED the batch containing this message was canceled through the API

Status: 200 OK

{
    "success":true,
    "result":{
        "reports":[ {
            "campaignKey":"THE_CAMPAIGN_KEY", "startDate":"2014-05-02", "endDate":"2014-06-02",
            "campaignStatus":[
                {"user":"john365", "date":"2014-06-02", "code":"PUSH_SENT", "device_id": "D24CAD72-5299-46D...", "details":"Push Sent"},
                {"user":"miranda32", "date":"2014-06-02", "code":"PUSH_SENT", "device_id": "713E3BB7-38AA-4D3F...", "details":"Push Sent"}
                ]
            }]
        }
}

Status: 404

{
"status": "404",
"success": false,
"error_message": "Unknown campaign key at index ..."
}

Status: 405

{
"status": "405",
"success": false,
"error_message": "Campaign not ready at index..."
}

Cancel a batch

API to cancel a batch previously scheduled using the transac campaign or through the product UI. It returns the batch as it was scheduled.

PUT /api/transac/campaignKey/requestID/cancel

Query parameters

Property Type Description Default
campaignKey string The campaign unique key for which you are retrieving stats. campaign_id should be used here required
requestId string The ID of the batch to cancel. Retrieved in the output of the transac POST call required

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaignKey":["CGN_ACMECORP_1401106808015"],
        "messages":[
            {
                "user":"john365",
                "templateVars":{"lastname":"Doe","firstname":"John","contractNumber":"ABC56"}
            },
            {
                "user":"duce23",
                "templateVars":{"lastname":"Duce","firstname":"JC","contractNumber":"234AE"}
            }
        ]
    }
}

Status: 404

{
"status": "404",
"success": false,
"error_message": "Unknown campaign"
}

Retrieve hits for a campaign

API to generate a status report of all message hits for a given transactional campaign.

GET /api/transac/campaignKey/hits?page=page&page_size=page_size

Query parameters

Property Type Description Default
campaignKey string The campaign unique key for which you are retrieving stats. campaign_id should be used here required
page integer The page of hits report to retrieve. Negative values causes a 400 error. 1
page_size integer The number of hits to retrieve per page. Range of values is [1..5000]. Values outside range cause a 400 error. 5000

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaignKey": "THE_CAMPAIGN_KEY",
        "page": 1,
        "page_size": 500,
        "hits":[
            {
                "user_id": "your_user_id_45",
                "time": "2015-11-11T09:51:42Z"
            },
            {
                "user_id": "your_user_id_215",
                "time": "2015-11-13T09:51:44Z"
            },
            {
                "user_id": "your_user_id_45",
                "time": "2015-11-13T09:52:04Z"
            }
        ]
        }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Invalid parameter value ..."
}

Status: 404

{
    "status": "404",
    "success": false,
    "error_message": "Unknown campaign key ..."
}

Retrieve hits per user for a campaign

API to generate a status report of the message hits, per user, for a given transactional campaign.

GET /api/transac/campaignKey/hits_per_user?page=page&page_size=page_size

Query parameters

Property Type Description Default
campaignKey string The campaign unique key for which you are retrieving stats. campaign_id should be used here required
page integer The page of hits report to retrieve. Negative values causes a 400 error. 1
page_size integer The number of hits to retrieve per page. Range of values is [1..5000]. Values outside range cause a 400 error. 5000

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaignKey": "THE_CAMPAIGN_KEY",
        "page": 1,
        "page_size": 500,
        "hits":[
            {
                "user_id": "your_user_id_215",
                "hits": 5
                "first_time": "2015-11-11T08:15:40Z",
                "last_time": "2015-11-13T09:51:44Z"
            },
            {
                "user_id": "your_user_id_215",
                "hits": 3
                "first_time": "2015-10-11T10:05:10Z",
                "last_time": "2015-11-13T09:51:00Z"
            },
        ]
    }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Invalid parameter value ..."
}

Status: 404

{
    "status": "404",
    "success": false,
    "error_message": "Unknown campaign key ..."
}