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.

Targeting

You can use the API to send a broadcast to all users or target segments, channels, users or installs.

User IDs

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.

Install IDs

Alternatively, if do not use User Association, you can still target the installs users are active on via installIds, the 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

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.

Install push details


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.


This is for the latest version of the API. Please see the Changelog for previous versions.

Sending notifications

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

Payload

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

{
  target: {
    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
  }
  content: {
    title: String, required
    message: String, required
    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
  }
  collapseId: String, a unique identifier for the device operating system to group and collapse related notifications.
  runBackgroundHandler: Boolean, when true the message will be sent for processing in the background (content-available flag in iOS)
  ios: {
      category: String, this will trigger your UNNotificationContentExtension whose ID matches this category.
      badge: {
        type: String, either "incrementBy" or "setTo"
        count: Positive or Negative integer. Set to 0 to clear badge.
      }
      sound: String, sound file to play instead of the default device notification sound. Pass 'none' to disable vibration and sound for the notification.
  }
  android: {
      highPriority: Boolean, sets priority flag to wake up Android devices
      sound: String, sound file that is included in your app to play instead of the default device notification sound.
  }
  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,
  }
  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 '{
        "target": { "broadcast": true },
        "content": {"title": "Hello World", "message": "from Kumulos Push" }
    }' "https://push.kumulos.com/notifications"

Sample PHP

<?php
    $postData = json_encode(array(
        "target" => [
          "broadcast" => true,
        ],
        "content" => [
          "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.

400 Bad Request

Your request was valid but all of the targeted users or installs do not exist or have unsubscribed from push notifications. No notification has been queued and the errors payload will describe the errors.

{
  notification: null,
  errors: {
      unknownInstallIds: ["uuid1"]
      unsubscribedInstallIds: ["uuid2"]
      unknownUserIds: [123]
      unsubscribedUserIds: [456]
  }
}

202 Accepted

Your request was accepted and queued.

The response body will contain a JSON object describing the notification object that was created as a result, along with an errors key which when present describes any users or installs that were targeted but do not exist or have unsubscribed.

{
  "notification": {
    "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
  },
  "errors": {
      unknownInstallIds: ["uuid1"]
      unsubscribedInstallIds: ["uuid2"]
      unknownUserIds: [123]
      unsubscribedUserIds: [456]
  }
}

Cancelling a scheduled notification

You can cancel a notification that has been scheduled to send in the future using the ID of the notification that was created as follows:

DELETE https://push.kumulos.com/v2/scheduled-notifications/{id}

Sample cURL

curl -X DELETE
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://push.kumulos.com/v2/scheduled-notifications/{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.

400 Bad Request

Your request was valid but the notification has already been sent (or has been cancelled).

{
    "error": "Notification already sent"
}

404 Not Found

A notification with the given ID could not be found.

204 No Content

Your request was accepted and processed - the notification has been cancelled.


Checking open rates

You can use the ID of the notification created to get the installs that 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"}
]

Using meta-data

If you use the User Association feature to identify your users to Kumulos from device SDKs and are making use of the userIds targeting option, then the userMeta, and reportingMeta fields give you a flexible way to target & report on push notifications.

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 geofence

POST https://push.kumulos.com/v1/geofences

Sample cURL

Circle Geofence

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "name": "Circular Geofence",
      "boundsGeoJson": {
        "type": "Feature",
        "properties": {
          "radius": 425
        },
        "geometry": {
          "type": "Point",
          "coordinates": [-73.9652551,40.7827647]
        }
      },
      "isEnabled": true,
      "tags": ["Tourism", "Nature"]
}' "https://push.kumulos.com/v1/geofences"

The boundsGeoJson object is in GeoJSON format and radius is specified in metres.

Polygon Geofence

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "name": "Polygon Geofence",
      "boundsGeoJson": {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [-73.95815849304199,40.80065354924362],
                [-73.98193359375,40.76802920702854],
                [-73.97309303283691,40.76432383634019],
                [-73.9493179321289,40.796949998204596],
                [-73.95815849304199,40.80065354924362]
              ]
            ]
          },
          "properties": {
            "orderAdded": [
              0, 1, 2, 3, 4
            ],
            "markerLocation": [
              40.783102, -73.965074
            ]
          }
      },
      "isEnabled": true,
      "tags": ["Tourism", "Nature"]
}' "https://push.kumulos.com/v1/geofences"

Again, the boundsGeoJson object is in GeoJSON format and the orderAdded array is required (to allow subsequent editing of the geofence points in the Kumulos UI).

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 geofence that was created as a result.

Circle Geofence Response

{
  "id": 1,
  "name": "Circular Geofence",
  "isEnabled": true,
  "boundsGeoJson": {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -73.9652551,
        40.7827647
      ]
    },
    "properties": {
      "radius": 425
    }
  },
  "activationCount": 0,
  "createdAt": "2019-06-28T13:48:34+0000",
  "updatedAt": "2019-06-28T13:48:34+0000",
  "activeUsers": 0,
  "appId": 1,
  "tags": [
    "Tourism",
    "Nature"
  ]
}

Polygon Geofence Response

{
  "id": 2,
  "name": "Polygon Geofence",
  "isEnabled": true,
  "boundsGeoJson": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-73.95815849304199,40.80065354924362],
          [-73.98193359375,40.76802920702854],
          [-73.97309303283691,40.76432383634019],
          [-73.9493179321289,40.79694999820459],
          [-73.95815849304199,40.80065354924362]
        ]
      ]
    },
    "properties": {
      "orderAdded": [
        0, 1, 2, 3, 4
      ],
      "markerLocation": [
        40.783102, -73.965074
      ]
    }
  },
  "activationCount": 0,
  "createdAt": "2019-06-27T12:24:08+0000",
  "updatedAt": "2019-06-27T12:24:08+0000",
  "activeUsers": 0,
  "appId": 1,
  "tags": [
    "Tourism",
    "Nature"
  ]
}

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


Changelog

v2

  • Added support for more detailed feedback on creation of notification
  • Deprecated v1 documentation