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
DELETE requests allow you to create, update, and delete those resources
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
data, which will vary according to the endpoint being used:
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
GET requests on our endpoints (without specifying any
id values in the URL) results in making a
“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 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:
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.
Fields listed as
"searchable": true in the
/template endpoints for each data type can be used to search your data.
operator must be one of the following:
||(less than or equal to)|
||(greater than or equal to)|
||(within a list of comma separated items)|
||(is null type)|
For example, searching your Subscribers for all everyone with the
first_name “Alex” would look like this:
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.