V1

Kumulos has a RESTful API that allows you to send or schedule push notifications, report on open rates / conversions and manage channels from any other backend system.

Install IDs

When sending notifications to specific users the Kumulos Push API uses installIds, these are unique identifiers within your app used by all the Kumulos services to cluster requests by the originating device. They are not used to authenticate your app, or a specific user of the app.

When it is initialized for the first time the Kumulos SDK will automatically generate a unique identifier for the device your App is installed on and will use this identifier for every subsequent interaction with our services.

If you want are using your own backend solution you will need to manage your own lookup to pair an installId with whatever identifier your app models devices or users with, an example of this interaction is shown in the diagram below.

Checking Push Registrations

When you run your app on a simulator or install your app on a device, you can check that the install has successfully registered for push notifications by selecting the app and clicking the Installs tab to see the ten most recent installs of your app. Click on any install and then click on Push tab.

Authentication

The Kumulos Push API authenticates other back-end services via HTTP Basic Auth using your app's API Key as the username and your Server Key as the password, both of these are available from the App Dashboard in your Agency Console.

Sending Notifications

POST https://push.kumulos.com/notifications

Payload

The request payload must be provided as a JSON object, with the following fields and validation rules met.

{
  broadcast: Boolean, when true the message will be sent to all registered devices
  installIds: Array of installIds to send the notification to
  userIds: Array of user identifiers to send the notification to
  userMeta: Object keyed by user identifier of meta-data for each user
  segmentId: Integer id of the segment to target
  segmentUuid: Unique identifier of the segment to target
  channelIds: Array of integer ids of the channel(s) to target
  channelUuids: Array of unique identifier(s) of the channel(s) to target
  excludeInstallIds:  Install Ids to be excluded from the results of a channel or segment target
  title: String, required
  message: String, required
  isBackground: Boolean, when true the message will be sent for processing in the background (content-available flag in iOS)
  url: String, set a url for the message to open in the device browser
  data: Optional object of additional key / values to be passed in the notification payload for your app to consume
  ios: {
      hasBadge: Boolean
      badgeType: String, either "incrementBy" or "setTo"
      badgeCount: Positive or Negative integer. Set to 0 to clear badge.
  }
  android: {
      highPriority: Boolean, sets priority flag to wake up Android devices
  }
  scheduled: Boolean
  schedule: {
      sendAt: DateTime of format "Y-m-d H:i", required if scheduled is true
      strategy: String, either "local" or "utc", required if scheduled is true
      pastTimes: String, either "ignore" or "nextDay", required if scheduled is true,
  }
  collapseId: String, sets the apns-collapse-id and the collapse_key options for APNS/FCM respectively.
  soundConfig: {
      iosSound: String, sound file to play instead of the default device notification sound. Pass 'none' to disable vibration and sound for the notification.
  }
  reportingMeta: Object of arbitrary meta-data about this notification
}

At least one of broadcast, installIds, userIds, segmentId / Uuid or channel Id / Uuid must be provided to send a notification.

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
        "broadcast": true,
        "title": "Hello World",
        "message": "from Kumulos Push"
    }' "https://push.kumulos.com/notifications"

Sample PHP

<?php
    $postData = json_encode(array(
        "broadcast" => true,
        "title" => "Test Broadcast",
        "message" => "Test from PHP")
    );

    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://push.kumulos.com/notifications",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
            'content-length: ' . strlen($postData),
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => $postData,
        CURLOPT_RETURNTRANSFER => true
    ] );

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
        echo "cURL Error #:" . $err;
    }
    else {
        echo $response;
    }
?>

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

201 Created

Your request was accepted and processed.

The response body will contain a JSON object describing the notification object that was created as a result.

{
  "appId":1,
  "source":1,
  "status":1,
  "filters": { "broadcast":true },
  "title":"Hello World",
  "message":"from Kumulos Push",
  "data":null,
  "updatedAt":"2017-01-01T00:00:00+0000",
  "createdAt":"2017-01-01T00:00:00+0000",
  "id":1
}

Checking open rates

You can then use the ID of the notification created to get the installs or users that have opened the notification. This will allow you to track who or which install has opened what message and when. Very useful if you are measuring the effectiveness of your push campaigns.

Retrieving the installs that opened the notification

GET https://push.kumulos.com/notifications/{id}/install-opens

Sample cURL

curl -X GET
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://push.kumulos.com/notifications/1/install-opens"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

200 OK

Your request was accepted and processed.

The response body will contain an array of JSON objects showing the install IDs that opened the notification along with the time that the open was recorded.

[
  {"installId":"abcdefgh","openedAt":"2017-01-01 00:00:00"},
  {"installId":"ijklmnop","openedAt":"2017-01-01 00:00:00"}
]

Retrieving the users that opened the notification

GET https://push.kumulos.com/notifications/{id}/user-opens

Sample cURL

curl -X GET
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://push.kumulos.com/notifications/1/user-opens"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

200 OK

Your request was accepted and processed.

The response body will contain an array of JSON objects showing the install IDs that opened the notification along with the time that the open was recorded.

[
  {"userId":"user-abcdefgh","openedAt":"2017-01-01 00:00:00"},
  {"userId":"user-ijklmnop","openedAt":"2017-01-01 00:00:00"}
]

Using Meta-Data & User-Targeted Push

The combination of the userIds, userMeta, and reportingMeta fields give you a flexible way to target & report on push notifications.

User ID Targeting

If you use the User Association feature to identify your users to Kumulos from device SDKs, you can make use of the userIds targeting option. For example, if you identify your users by a 'membership number', you can associate that number with each installation when a user logs in.

Then once associated, you can send push notifications to the users identified by their membership number instead of the Kumulos install ID.

Reporting Meta-Data

When sending a notification, you may wish to associate meaningful meta-data with the notification. This meta-data will be reflected in the data field of any push events generated as a result of the notification and the user's interaction with the notification.

For example, if you wanted to send a campaign identifier, you could add the following to the send notification request:

{
  ...
  "reportingMeta": {
    "campaign": "Summer Promotion"
  }
}

User Meta

User meta-data extends the concept of reporting meta-data to the user level when targeting pushes based on user identifiers.

For example, if sending to users, you can include meta-data specific to each user which will be reflected in any push events related to that user's notification & interactions with the message.

For example, if for each member you wanted to pass their current sequence number in a drip-feed content flow:

{
  ...
  "userIds": ["member-id-1", "member-id-2"],
  "userMeta": {
    "member-id-1": { "messageSequenceNumber": 1 },
    "member-id-2": { "messageSequenceNumber": 3 }
  }
}

Creating a channel

POST https://push.kumulos.com/channels

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "uuid": "channel-uuid",
      "name": "friendly name"
      "showInPortal": true
      "meta": {
          "additional": "data"
      }
}' "https://push.kumulos.com/channels"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

201 Created

Your request was accepted and processed.

The response body will contain a JSON object describing the channel that was created as a result.

    {
      "appId":1,
      "uuid":"channel-uuid",
      "name":"Channel Name",
      "showInPortal":true,
      "meta": {
        "additional":"data"
      },
      "updatedAt":"2017-02-16 14:43:03",
      "createdAt":"2017-02-16 14:43:03",
      "id":1
    }

Updating a channel

PUT /channels/{id}

Sample cURL

curl -X PUT
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "uuid": "channel-uuid",
      "name": "friendly name"
      "showInPortal": true
      "meta": {
          "additional": "data"
      }
}' "https://push.kumulos.com/channels/{id}"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

200 Success

Your request was accepted and processed.

The response body will contain a JSON object describing the channel in its updated state.

    {
      "appId":1,
      "uuid":"channel-uuid",
      "name":"Channel Name",
      "showInPortal":true,
      "meta": {
        "additional":"data"
      },
      "updatedAt":"2017-02-16 14:43:03",
      "createdAt":"2017-02-16 14:43:03",
      "id":1
    }

Deleting a channel

DELETE /channels/{id}

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
   "https://push.kumulos.com/channels/{id}"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

204 No Content

Your request was accepted and processed.

Subscribing installs to a channel

POST /channels/{id}/subscriptions

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

404 Not Found

Your request has a non-existent install id.

204 No Content

Your request was accepted and processed.

Subscribing users to a channel

POST /channels/{id}/subscriptions

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "userIds": ['user-1', 'user-2']
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

404 Not Found

Your request has a non-existent user id.

204 No Content

Your request was accepted and processed.

Unsubscribing installs from a channel

DELETE /channels/{id}/subscriptions

Sample cURL

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

404 Not Found

Your request has a non-existent install id.

204 No Content

Your request was accepted and processed.

Unsubscribing users from a channel

DELETE /channels/{id}/subscriptions

Sample cURL

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "userIds": ['user-1', 'user-2']
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

404 Not Found

Your request has a non-existent user id.

204 No Content

Your request was accepted and processed.

Calling from KScript

If you have multiple apps on Kumulos and you want an event in one app to trigger a push notification to an install of another app, you can do this using the HTTP client in a Kscript method.

var username = 'API Key of your other Kumulos app';
var password = 'Server Key of your other Kumulos app';
var auth = base64_encode( username + ':' + password );

var client = K.http.createClient('https://push.kumulos.com');
var headers =
{
  'Authorization': 'Basic ' + auth,
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};


var params =
{
  'broadcast': true,
  'title' : 'Hello',
  'message': 'World'
};

var response = client.post('notifications', K.JSON.stringify(params), headers);

if (response.isError()) {
    K.log(res.getBody());
}

If you have companion apps with different push notification certificates and API methods but you want two apps to share the same a backend database tables (for example: to access the Install IDs of the other app), please contact technical support who can arrange this.