Kumulos has a RESTful API that allows you to send or schedule push notifications, check report 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.

Managing install IDs

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
  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.       
  }
  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, a unique identifier for the device operating system to group and collapse related notifications.
}

At least one of broadcast, installIds, 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 which installs have opened the notification. This will allow you to track who has opened what message and when. Very useful if you are measuring the effectiveness of your push campaigns.

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

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.

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.

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.