Cerkl API

Cerkl is a platform built to put personalized Content in front of an Audience of targeted Subscribers, such as your company's employees or a group of external customers or vendors. While all of this can be accomplished in our application's user interface (UI), it can be useful to leverage our RESTful API to manage both your Cerkl Audience and the Content they're presented with programmatically.

Once you've authenticated with our OAuth 2.0 servers and have a secure access key for your Cerkl instance, you can perform a variety of operations to automate your Cerkl workflows and make your data work for you. Our RESTful API provides GET requests that will allow you to inspect your Cerkl Audience and Content as they are stored on our servers, and POST, PUT and DELETE requests allow you to create, update, and delete those resources as needed.

Here you can access resources on topics important to understanding what Cerkl does and how you can use it in your software integrations, including helpful examples and illustrations to link our API endpoint functionality to what users see in our UI. Most of our examples are provided using cURL.

Cerkl API Request Basics

Cerkl's RESTful API has many different methods availalbe for you to interact with your organization's data. In addition, our data models have a plethora of fields available to store complex information about your Subscribers, Segments, Blasts, and Content. It's important to understand the basis of our request body templates in order to use our API successfully.

Each request body used in our API is constructed from a JSON template that designates the API version (3.0) and the payload's data, which will vary according to the endpoint being used:

{
    "template": {
        "version": "3.0",
        "data": [
            {
                ...
            }
        ]
    }
}

You can see how to construct your payload data for each request in the rest of the core documentation and our API Reference page.

"Get All" Requests

Performing GET requests on our endpoints (without specifying any id values in the URL) results in making a GET "all" request on that type of data. For example: making a GET request on the /subscriber endpoint will retrieve all of your organization's Subscribers, though this information is returned in pages. A naked "GET all" will always default to getting you the first "page" of 100 entries of data from your endpoint (i.e. the first 100 Subscribers, Segments, Categories... etc.) You can supply page_size and page data to your request in order to specify how many entries you would like to retrieve and where to start, respectively.

For example, to return the first page of your organization's Segments but only the first 3 entries, you could do this:

$ curl -G 'api.cerkl.com/v3/segment' \
    --header 'Authorization: Bearer e37b98a75db58f83edaaccdb75d15c3a38ae5e38' \
    --data-urlencode 'page=1' \
    --data-urlencode 'page_size=3' \

Filtering/Searching Cerkl Data

Certain fields are searchable in some of our data models by including a filters_json key in your "GET all" requests. This functionality allows you to designate which properties to search and which comparison operators to use.

{
    "property name": {
        "operator": value to search
    },
    "another property name": {
        "operator": value to search
    }
}

Fields listed as "searchable": true in the /template endpoints for each data type can be used to search your data. The property operator must be one of the following:

For example, searching your Subscribers for all everyone with the first_name "Alex" would look like this:

$ curl -G 'api.cerkl.com/v3/subscriber' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-urlencode 'filters_json={"first_name": {"eq": "Alex"}}'

Be sure to review which fields are searchable in our API Reference to see how you can use the filters_json functionality to your advantage.