Skip to content

CRM

Kumulos has a RESTful API that allows you to fetch existing users and to manage users' attributes for future targeting with segments and/or the Messaging API.

Headers

Please ensure that you set the following headers in your request:

Content-Type: application/json
Accept: application/json

Authentication

The Kumulos CRM API authenticates via HTTP Basic Auth using your app's API Key as the username and your Server Key as the password (in the Authorization header). Both of these are available from the App Dashboard in your Agency Console.

Users

The API allows you to read pages of users.

Read users

GET https://crm.kumulos.com/v2/users?currentPage=1&numberPerPage=50

Note that the URL must have the mandatory query parameters currentPage and numberPerPage. The maximum number of users per page is 1000.

It returns all non-anonymous (created via associateUserWithInstall call in your mobile app) users as well as anonymous (created by system) users currently associated with an install. Hence, it does not return anonymous users which are not current users on any install.

Each user contains an array of installs with relevant installation information (see below).

Sample cURL

curl -X GET
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://crm.kumulos.com/v2/users?currentPage=1&numberPerPage=50"

Sample PHP

<?php
    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://crm.kumulos.com/v2/users?currentPage=1&numberPerPage=50",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "GET",
        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 had invalid query parameters. The response body will return a JSON object describing what keys were not present or had invalid values.

200 OK

Your request was processed. The response body will contain a JSON object with users and pagination information.

{
    "users": [
        {
            "identifier": "user-1", // Unique user identifier
            "attributes": { // Attributes for the user
                "attributeKey": "attributeValue"
            },
            "firstActive": "2020-10-20T08:00:00+00:00", // When user was first active
            "lastActive": "2020-11-20T08:00:00+00:00", // When user as last active
            "inAppEnabled": false,// Is in-app messaging enabled for the user
            "createdAt": "2020-10-20T08:00:00+00:00", // When user row was created
            "updatedAt": "2020-10-20T08:12:00+00:00", // When user row was updated
            "installs": [
                {
                    "id": "install-1", // Unique install identifier
                    "subscribedToPushNotifications": true, // Is install subscribed to push notifications
                    "os": "Android",
                    "osVersion": "10",
                    "sdkType": "Xamarin",
                    "sdkVersion": "2.2.2",
                    "lastActive": "2020-12-09T12:00:00+00:00", //When install was last active
                    "appVersion": "id-1",
                    "countryIsoCode": "GB",
                    "timezone": "Africa/Algiers", //IANA timezone
                    "locale": "US",
                    "deviceModel": "mia2",
                    "deviceName": "Xiaomi Mi A2"
                },
                ...
            ]
        },
        ...
    ],
    "totalUsers": 4,
    "currentPage": 1
}

Attributes

The API allows you to read, set and delete user attributes.

Read attributes

GET https://crm.kumulos.com/v1/users/{user-id}/attributes

Sample cURL

curl -X GET
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://crm.kumulos.com/v1/users/{userId}/attributes"

Sample PHP

<?php
    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://crm.kumulos.com/v1/users/{userId}/attributes",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "GET",
        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.

404 Not found

User with specifier user identifier does not exist.

200 OK

Your request was processed. The response body will contain a JSON object with user attributes. If user does not have any attributes set, the JSON object will be empty.

{
    "name" : "Mark",
    "isCustomer" : true,
    "age" : 40
}

Set attributes

PUT https://crm.kumulos.com/v1/users/{user-id}/attributes

Payload

Attributes can then be passed in as a raw JSON object in the body.

{
  "name" : "Mark",
  "isCustomer" : true,
  "age" : 40
}

Please ensure that you are using the same user ids as your mobile app is passing into the associateUserWithInstall() method as a new user will be created the specified user id if one does not already exist.

Also, please note that last write wins, so this call will overwrite any attributes set by your mobile app (in the associateUserWithInstall() method) and vice versa.

Sample cURL

curl -X PUT
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
        "name": "Mark",
        "isCustomer" : true,
        "age" : 40
    }' " https://crm.kumulos.com/v1/users/{user-id}/attributes"

Sample PHP

<?php
    $postData = json_encode(array(
        "name" => "Mark",
        "attributes" => [
          "name": "Mark",
          "isCustomer" : true,
          "age" : 40
        ]
    ));

    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://crm.kumulos.com/v1/users/{user-id}/attributes",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
            'content-length: ' . strlen($postData),
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "PUT",
        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 or contained invalid JSON. The response body will return a JSON object describing what keys were not present or had invalid values.

200 OK

Your request was processed. A new user will have been created with the specified user id, if one did not already exist, and attributes set. The response body will contain a JSON object describing the user that was created or updated as a result.

{
  "identifier": "{user-id}",
  "attributes": {
    "name" : "Mark",
    "isCustomer" : true,
    "age" : 40
  }
}

Delete attributes

DELETE https://crm.kumulos.com/v1/users/{user-id}/attributes

Sample cURL

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    "https://crm.kumulos.com/v1/users/{user-id}/attributes"

Sample PHP

<?php
    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://crm.kumulos.com/v1/users/{user-id}/attributes",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "DELETE",
        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.

400 Bad Request

Your request was valid but a user with the specified user id could not be found.

204 No Content

Your request was processed and the attributes have been deleted for the specified user.