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 a single user by their identifier, or paged results of all users.

Read user¶

`GET https://crm.kumulos.com/v2/users/{userIdentifier}`¶

Returns the user matching the specified identifier, along with any installs they have been associated with.

User identifiers should be URL encoded as part of the request path.

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/user-1"

Sample PHP¶

<?php
    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://crm.kumulos.com/v2/users/user-1",
        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 Unprocessable Entity¶

No user matching the specified identifer was found.

200 OK¶

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

{
    "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"
        },
        ...
    ]
}

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.

CRM

Headers¶

Authentication¶

Users¶

Read user¶

GET https://crm.kumulos.com/v2/users/{userIdentifier}¶

Sample cURL¶

Sample PHP¶

Responses¶

401 Unauthorized¶

404 Unprocessable Entity¶

200 OK¶

Read users¶

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

Sample cURL¶

Sample PHP¶

Responses¶

401 Unauthorized¶

422 Unprocessable Entity¶

200 OK¶

Attributes¶

Read attributes¶

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

Sample cURL¶

Sample PHP¶

Responses¶

401 Unauthorized¶

404 Not found¶

200 OK¶

Set attributes¶

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

Payload¶

Sample cURL¶

Sample PHP¶

Responses¶

401 Unauthorized¶

422 Unprocessable Entity¶

200 OK¶

Delete attributes¶

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

Sample cURL¶

Sample PHP¶

Responses¶

401 Unauthorized¶

400 Bad Request¶

204 No Content¶

`GET https://crm.kumulos.com/v2/users/{userIdentifier}`¶

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

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

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

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