Cerkl API Concepts

OVERVIEW

Cerkl is a platform built to put personalized Content in front of an Audience of targeted Subscribers, to achieve this, it can be done from our user interface (UI), but also using our RESTfull API.

EFFORT

Advanced
This is an approximation based on average time spend for existing Cerkl Broadcast clients.

ROLES

Comms Expert
Network Security Expert
Web Server Expert
These are the suggested technical resources needed to complete this task.

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:

Operator Comparison
eq (equal)
neq (not equal)
lt (less than)
lte (less than or equal to)
gt (greater than)
gte (greater than or equal to)
in (within a list of comma separated items)
isnull (is null type)

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.

Concepts

Subscribers

Subscribers make up your Cerkl Audience, the contacts who will receive the communications you send in the form of Blasts and Content. Many different kinds of data can be attached to Subscribers, allowing you to add information that can strongly identify your audience and allow you to control who is receiving the content from your organization’s communicators. As shown in our API Reference, in addition to their names and email addresses, Subscribers can contain a collection of values that describe their position in your organization.

Subscribers and Segments

If you’re looking for information on how to interact with Segments that Subscribers can be associated with and how they are added to and removed from those lists, see the Segments documentation. Are you working with and need to inspect Subscribers associated with a particular Category? Check out our Categories page.

Subscriber Privacy and Content Controls

Importantly, Cerkl designates both a subscriber_privacy_level and a subscriber_status for each Subscriber, controlling whether their Cerkl experience will be personalized and what types of Content they can receive from Cerkl, respectively. It is required that these values are provided to request bodies when adding or updating Subscribers.

Subscriber Privacy Level

Subscriber personalization is an important aspect of Cerkl’s operation. As described in the Content pages, Stories appearing in a Subscriber’s News Digests are controlled by the Subscriber’s interests. Cerkl’s machine learning software will do its best to present Subscribers with Content they’re likely to engage with, but personalization can help. It is recommended that all Cerkl Subscribers are allowed to personalize to get the most out of what Cerkl is capable of doing. Subscriber personalization levels are controlled using subscriber_privacy_level ID values as shown in the table below:

Subsciber Privacy Level ID Privacy Level Description
1 Personalizes the Subscriber's experience
2 Personalizes the Subscriber’s experience but does not report on their activity
3 Does not personalize the Subscriber’s experience

The different Subscriber Privacy Levels can also be accessed by making a GET request to the /subscriber_privacy_level endpoint:


$ curl --request GET 'api.cerkl.com/v3/subscriber_privacy_level' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Subscriber Status

Cerkl API v3 uses 4 distinct Subscriber Status IDs to control whether or not they will receive Blasts and/or Content (via News Digests):

Subscriber Status ID Status ID Description
1 Subscriber is unsubscribed from all Blasts and News Digests
2 Receive email Blasts only
3 Receive News Digests only
4 Receive email Blasts and News Digests

Like Subscriber Privacy Levels, Subscriber Statuses can be accessed from the API as well. This is done using a GET request to the /subscriber_status endpoint:


$ curl --request GET 'api.cerkl.com/v3/subscriber_privacy_level' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Importantly, subscriber_status ID 1 cannot be used directly, as it is reserved for when a Subscriber is unsubscribed from a Cerkl instance. subscriber_status ID values 2 and 3 can be used, but it is highly recommended that all Cerkl Subscribers be initially set to subscriber_status ID 4 to use Cerkl most effectively.

Adding a Subscriber

Subscribers can be added to your Cerkl by making a POST request to the /subscriber endpoint with a valid payload. At a minimum, your payload must include (beyond the normal template) a first name, last name, email address, valid subscriber_status ID object and valid subscriber_privacy_level ID object:


{{
$ curl --request POST 'api.cerkl.com/v3/subscriber' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "first_name": "Jerry",
                        "last_name": "Garcia",
                        "email": "jerry@shakedownstreet.com",
                        "subscriber_status": {
                            "id": 4
                        },
                        "subscriber_privacy_level": {
                            "id": 1
                        }
                    }
                ]
            }
        }'
}}

Getting Subscribers

You can inspect your Subscribers and their data by using GET requests to the /subscriber endpoint (see the Cerkl API page for more information on “get all” methods):


{{
$ curl --request GET 'api.cerkl.com/v3/subscriber' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}}

You can also retrieve specific Subscribers by making a GET request to the /subscriber/{id} endpoint and supplying an existing Subscriber’s valid integer id value to the request body. For example: if Jerry’s id is 12345, we can retrieve their data like this:


{{
$ curl --request GET 'api.cerkl.com/v3/subscriber/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}}

Updating Subscribers

Existing Subscribers can be updated using the PUT method on the /subscriber/{id} endpoint, where the supplied integer id value designates the Subscriber to be altered. If Jerry’s id is still 12345, but we want to downgrade his subscriber_status to “blasts only” — an ID of 2 — the request would look something like this:


{{
$ curl --request PUT 'api.cerkl.com/v3/subscriber' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "first_name": "Jerry",
                        "last_name": "Garcia",
                        "email": "jerry@shakedownstreet.com
                        "subscriber_status": {
                            "id": 2
                        },
                        "subscriber_privacy_level": {
                            "id": 1
                        }
                    }
                ]
            }
        }'
}}

Deleting (Unsubscribing) Subscribers

Removing Subscribers via Cerkl’s API doesn’t actually “delete” them, but rather unsubscribes them from your organization’s Cerkl where they will remain to ensure they don’t receive further communications. This operation transforms the “deleted” Subscriber to an “Unsubscribe” object in order to keep a record of this change. See the Unsubscribes documentation for more information on how to interact with those objects.

To unsubscribe a Subscriber from your organization’s Cerkl where the Subscriber’s id is 12345, for example, make a POST request to the /subscriber/{id}/unsubscribe endpoint, like so:


{{
$ curl --request POST 'api.cerkl.com/v3/subscriber/12345/unsubscribe' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}} 

Our unsubscription endpoint also allows you to supply additional information about why the Subscriber was removed, with information such as termination_date_utc, termination_voluntary, and departure_code allowing you to optionally specify when and why a Subscriber may have been removed. Using the same Subscriber’s id of 12345, you could specify that information like this:


{{
$ curl --request POST 'api.cerkl.com/v3/subscriber/12345/unsubscribe' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "termination_date_utc": "2020-08-01 12:00:00",
                        "termination_voluntary": true,
                        "departure_code": {
                            "id": 6
                        }
                    }
                ]
            }
        }'
}}

Using the request above, this Subscriber is recorded as having been removed from their Cerkl Audience because they left the organization voluntarily. The Subscriber Departure Code used was 6. designating the Subscriber retired from their organization. Subscriber Departure Code values are described in more detail below.

Subscriber Departure Codes

There are a lot of reasons why a Subscriber might leave your Cerkl Audience. If you choose to specify why they’re no longer going to be receiving communications from you, the 12 different Subscriber Departure Codes can be an easy and helpful way to do so.

The different Subscriber Departure Codes can be easily accessed using our API, as with many of our other resources. This can be done by making a GET request to our /subscriber_departure_code endpoint, which will provide you with a list of the id values and their descriptions.

Subscriber Insights

Cerkl gathers data about how Subscribers interact with the Content delivered to them, allowing us to determine how much a user has engaged with that Content and what they are most interested in based upon how they use Cerkl. For more information, see our Subscriber Insights documentation.

Because Cerkl gathers data about how Subscribers interact with Content, you can also query the Insights for a particular Content piece. For more information, see our Content Insights documentation.

Content

In Cerkl terms, “Content” means Events, Stories and Links added to your Cerkl instance by users or external RSS or Atom feeds. Content appears to your Subscribers in their personalized News Digests, which present them with the types of Content (based on Categories) they’re most interested in.

Programmatically, each of these types of Content can be added, updated, and deleted using their own endpoints (e.g. POST a Story using /story, PUT, or DELETE a Story using /story/{id}). However, to GET Content, you must use the /content endpoint to retrieve all of the Content in a Cerkl and /content/{id} to retrieve a certain piece of Content specified by its Cerkl id.

For example, if you’ve authenticated with a Cerkl instance, you can get all of its content like this:


{{
$ curl --request GET https://api.cerkl.com/v3/content \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}}

Remember: all Cerkl GET endpoints that don’t target specific id values function as “GET all” requests. As with all of our other “GET all” functionality, you can specify page (defaults to 1) and page_size (defaults to 100) parameters to control the amount of information returned to you.


{{
$ curl --request GET https://api.cerkl.com/v3/content \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        -G -d page=1 -d page_size=100
}}

Adding and Updating Content

As mentioned above, you will need to use the specific endpoints associated with each type of Content in order to perform create (POST), update (PUT), and delete (DELETE) operations. See the Events and Stories pages for information on using those specific endpoints.

Content Insights

Because Cerkl gathers data about how Subscribers interact with Content, you can also query the Insights for a particular Content piece. For more information, see our Insights documentation.

Stories

Stories are articles that you are presenting to your Cerkl Subscribers. These can include company-wide communications that you want to appear in your Subscribers’ personalized News Digests and articles you think different people in your Audience might find interesting.

Adding Stories

To add Stories, POST to the /story endpoint:


{{
$ curl --request POST 'api.cerkl.com/v3/story' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                {
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": ,
                        "self": "string"
                    },
                    "priority_until_date_utc": "string",
                    "publish_date_utc": "string",
                    "expiration_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "evergreen": ,
                    "self": "string"
                }
            ]
        }
    }'
}}

Retrieving Stories

Stories are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Story Content).

Updating Stories

To update an existing Story, utilize the PUT method on the /story/{id} endpoint, constructing your URL with the id of the existing Story. If your Story’s ID is 12345, that looks like this:


{{
$ curl --request PUT 'api.cerkl.com/v3/story/12345' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                {
                    "id": ,
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": ,
                        "self": "string"
                    },
                    "priority_until_date_utc": "string",
                    "publish_date_utc": "string",
                    "expiration_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "evergreen": ,
                    "self": "string"
                }
            ]
        }
    }'
}}

Deleting Stories

To delete an Story, you just need to make a DELETE request to the Story/{id} endpoint using the id corresponding to your Story. If our Story id is still 12345 as it was above, that looks like this:


{{
$ curl --location --request DELETE 'api.cerkl.com/v3/story/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}}

Events

Event Content represents an upcoming event that you would like to announce to your Cerkl Subscribers in their News Digests. Events include information about the Event location, start and end times, and links to any registration links your Subscribers need to know about.

Adding Events

To add Events, POST to the /event endpoint:


{{
$ curl --request POST 'api.cerkl.com/v3/event' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "string",
                "data": [
                {
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": ,
                        "self": "string"
                    },
                    "priority_until_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "event_location": "string",
                    "event_street_address": "string",
                    "event_city": "string",
                    "event_postal_code": "string",
                    "event_region": "string",
                    "event_country": "string",
                    "event_all_day": ,
                    "event_start_date_time_utc": "string",
                    "event_end_date_time_utc": "string",
                    "event_time_zone": {
                        "id": ,
                        "self": "string"
                    },
                    "event_registration_url": "string",
                    "external_url": "string",
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "self": "string"
                  }
                ]
            }
        }'
}}

Retrieving Events

Events are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Event Content).

Updating Events

To update an existing Event, utilize the PUT method on the /event/{id} endpoint, constructing your URL with the id of the existing event. If your Event’s ID is 12345, that looks like this:


{{
$ curl --request PUT 'api.cerkl.com/v3/event/12345' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                {
                    "id": ,
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": 
                    },
                    "priority_until_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "event_location": "string",
                    "event_street_address": "string",
                    "event_city": "string",
                    "event_postal_code": "string",
                    "event_region": "string",
                    "event_country": "string",
                    "event_all_day": ,
                    "event_start_date_time_utc": "string",
                    "event_end_date_time_utc": "string",
                    "event_time_zone": {
                        "id": ,
                        "self": "string"
                    },
                    "event_registration_url": "string",
                    "external_url": "string",
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "self": "string"
                }
            ]
        }
    }'
}}

Deleting Events

To delete an Event, you just need to make a DELETE request to the event/{id} endpoint using the id corresponding to your Event. If our Event id is still 12345 as it was above, that looks like this:


{{
$ curl --location --request DELETE 'api.cerkl.com/v3/event/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
}}

Links

Link Content allows you to link external articles (from other websites and CRMs) to Cerkl. Links behave very similarly to Stories, but they let the external URL do most of the work for you. When other content is linked with a

Adding Links

To add Links, POST to the /link endpoint:


$ curl --request POST 'api.cerkl.com/v3/link' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                {
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "external_url": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": ,
                        "self": "string"
                    },
                    "priority_until_date_utc": "string",
                    "publish_date_utc": "string",
                    "expiration_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "evergreen": ,
                    "self": "string"
                }
            ]
        }
    }'

Retrieving Links

Links are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Link Content).

Updating Links

To update an existing Link, utilize the PUT method on the /link/{id} endpoint, constructing your URL with the id of the existing Link. If your Link’s ID is 12345, that looks like this:


$ curl --request PUT 'api.cerkl.com/v3/link/12345' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                {
                    "id": ,
                    "author": {
                        "id": ,
                        "self": "string"
                    },
                    "title": "string",
                    "summary": "string",
                    "body": "string",
                    "external_url": "string",
                    "more_button_text": "string",
                    "image_url": "string",
                    "categories": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "external_id": "string",
                    "priority": {
                        "id": ,
                        "self": "string"
                    },
                    "priority_until_date_utc": "string",
                    "publish_date_utc": "string",
                    "expiration_date_utc": "string",
                    "private": ,
                    "segments": [
                        {
                            "id": ,
                            "self": "string"
                        }
                    ],
                    "exclusive_to_segment": ,
                    "available_in_aptly": ,
                    "enable_comments": ,
                    "enable_link_tracking": ,
                    "status": {
                        "id": ,
                        "self": "string"
                    },
                    "evergreen": ,
                    "self": "string"
                }
            ]
        }
    }'

Deleting Links

To delete a Link, you just need to make a DELETE request to the link/{id} endpoint using the id corresponding to your Link. If our Link id is still 12345 as it was above, that looks like this:


$ curl --location --request DELETE 'api.cerkl.com/v3/link/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Unsubscribes

When Subscribers are “deleted” or unsubscribed from your organization’s Cerkl, they don’t disappear entirely. Cerkl keeps a record of all unsubscribed Subscribers in order to track that they have been Subscribers at some point but aren’t anymore (for whatever reason). This prevents users who opt out of communications from Cerkl from receiving any Cerkl messages.

Because these “Unsubscribers” are kept in our database, you can retrieve them to inspect who is no longer Subscribed to your Cerkl instance.

Getting All Unsubscribes

To get all of your Cerkl’s Unsubscribes, use the GET method on the /unsubscribe endpoint:


$ curl --request GET 'api.cerkl.com/v3/unsubscribe' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Getting Specific Unsubscribes

In order to retrieve specific Unsubscribes, you can make a GET request to the /unsubscribe/{id} endpoint, supplying an id integer value that corresponds to a specific Subscriber that was Unsubscribed. Unsubscribe objects retain the id values of the Subscriber objects they were originally.

For example, if a Subscriber with an id value of 12345 is unsubscribed, it becomes an Unsubscribe object with the same id:


$ curl --request GET 'api.cerkl.com/v3/unsubscribe/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Segments

Segments are logical separations of Cerkl Subscribers, similar in concept to distribution lists. Subscribers can be part of one segment, multiple segments, or no segments at all. You may notice that the Cerkl application offers users the ability to create Dynamic Segments with rulesets that allow you to include Subscribers that meet certain criteria. Importantly, only “normal”, non-dynamic Segments can be created via the API.

Creating a Segment

Creating a Segment can be done by making a POST request to our /segment endpoint. As with other objects, Segments can be assigned an external_id in an API call in order to conceptually connect it to distribution lists in external systems. If no external_id value is supplied during Segment creation you can always add one later. Also, as with all other Cerkl data objects, an internal id value is automatically assigned to a Segment upon successful creation. The Segment’s description string functions as its name.


$ curl --request POST 'api.cerkl.com/v3/segment' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "description": "Engineers",
                        "external_id": "12345"
                    }
                ]
            }
        }'

Retrieving Existing Segments

Once created successfully, the response body from the API will contain the Segment’s data, including the id value that can be used to reference it in other operations. As with other data objects, the Segment’s data can also be retrieved using a GET request to our /segment endpoint (to get all Segments):


$ curl --request GET 'api.cerkl.com/v3/segment' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

To get a specific existing Segment, use the /segment/{id} endpoint with the Segment’s id known value. For example, to get a Segment that has an id of 558904, you can use the following request:


$ curl --request GET 'api.cerkl.com/v3/segment/558904' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

As with other Cerkl data, Segments can be filtered by the values in their fields to search for those that meet certain criteria. Check out our API Reference for more details on searchable fields. As an example, here’s how you can find all of your Segments that have been updated since 2020-07-16 00:00:00 (UTC):


$ curl -G 'api.cerkl.com/v3/segment' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-urlencode 'filters_json={"date_modified_utc": {"gt": "2020-07-16 00:00:00"}}'

Adding Subscribers to a Segment

Adding Subscribers to Segments is done by making a POST request to our /segment/{segment_id}/subscriber endpoint. Logically, this operation is adding the particular segment_id (just listed as id in the Segment’s data) to the Subscriber’s record. Using this endpoint, you need to provide the id of the segment in the URL and the Subscriber’s id in the request body, and then that particular Subscriber’s data will contain a reference to the Segment.

For example, where the segment_id is 12345 and a Subscriber’s id is 98765, this request looks like this:


$ curl --request POST 'api.cerkl.com/v3/segment/12345/subscriber' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "id": 98765
                    }
                ]
            }
        }'

Note: only one Subscriber can be added to a Segment at a time using this method.

Getting All Subscribers in a Segment

If you need to retrieve all of the Subscribers associated with a particular Segment, just use a GET method on the /segment/{segment_id}/subscriber endpoint.

For instance, if you want to get all of your organization’s Subscribers in a Segment with an id value of 12345, you could use the following request:


$ curl --request GET 'api.cerkl.com/v3/segment/12345/subscriber' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Removing Subscribers From a Segment

To remove Subscribers from a Segment, use a DELETE method on the /segment/{segment_id}/subscriber/{subscriber_id} endpoint. Supplying valid (corresponding to existing data) integers for both the segment_id and subscriber_id fields will delete the Subscriber with id == subscriber_id from the Segment with id == segment_id.

For example, where segment_id is 12345 and the subscriber_id is 98765, the request would look like the following:


$ curl --request DELETE 'api.cerkl.com/v3/segment/12345/subscriber/98765' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Updating a Segment

Segment information (external_id and description) can be changed using a PUT request to our /segment/{id} endpoint:


$ curl --request PUT 'api.cerkl.com/v3/segment/558904' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "description": "New Segment Name",
                        "external_id": "new_external_id"
                    }
                ]
            }
        }'

Deleting a Segment

Deleting a Segment only requires the Segment’s id value:


$ curl --location --request DELETE 'api.cerkl.com/v3/segment/558904' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Note: deleting a Segment does not delete Subscribers.

Categories

Categories are determined by the main interests your organization covers within its content. Subscribers will select Categories they are interested in and not interested in when they personalize their Cerkl profile via the Welcome Email they will receive upon subscription. Cerkl will also suggest new Categories based upon the interests of your Audience and the keywords our AI will compare your Content with.

You can add Categories to your Stories and Events, allowing you to direct your Content towards the Subscribers most likely to engage with it.

Adding New Categories

If you would like to add a new Category, make a POST request to the /category endpoint that specifies its name in the description field:


$ curl --request POST 'api.cerkl.com/v3/category' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                        "description": "Engineering"
                    }
                ]
            }
        }'

Now you have a new Category your organization’s communicators can add to your Cerkl Content!

Getting Categories

Categories can be retrieved like all other Cerkl objects by using a GET request on the /category endpoint:


$ curl --request GET 'api.cerkl.com/v3/category' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

In order to retrieve a specific Category, you can use the GET method on the /category/{id} endpoint, specifying your Category via its integer id value. As an example, let’s say our newly created Category from above was given an id of 554. That request would look like this:


$ curl --request GET 'api.cerkl.com/v3/category/554' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Deleting Categories

Categories can be deleted using the DELETE method on the /category/{id} endpoint, where id specifies the Category to be removed. If your Category’s id value is still 554, that looks like this:


$ curl --request DELETE 'api.cerkl.com/v3/category/554' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Blasts

Blasts are email communications targeted at a certain group of your Subscribers (or all of them if you’re feeling dangerous). While Cerkl’s UI provides a complete Blast building experience, you can also generate and manage them programmatically should you choose to do so.

Adding Blasts

To add a Blast, make a POST request to our /blast endpoint. Your request body must contain a minimum


$ curl --request POST 'api.cerkl.com/v3/blast' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                            "status": {
                                "id": 0
                            },
                            "blast_template": {
                                "id": 0
                            },
                            "blast_merge_fields": [
                                {
                                    "id": 0,
                                    "type": {
                                        "id": 0
                                    },
                                    "value": "string"
                                }
                            ],
                            "name": "string",
                            "reply_to_email": "string",
                            "reply_to_name": "string",
                            "subject": "string",
                            "message": "string",
                            "target_segments": [
                                {
                                    "id": 0
                                }
                            ],
                            "target_categories": [
                                {
                                    "id": 0
                                }
                            ],
                            "target_conditional": {
                                "id": 0
                            },
                            "date_scheduled_utc": "string"
                    }
                ]
            }
        }'

Note: the domain of the reply_to_email address must match the domain of the verified reply-to email address for News Digests.

Blast Statuses

There are 4 different Blast Status IDs that can be used to fulfill the status id field in a Blast request body. These status values control what happens to a Blast when it is created or updated.

Blast Status ID Blast Status Description
1 Draft
2 Sending now
3 Scheduled
4 Sent

You can also retrieve these Blast Status ID values using the API by hitting our /blast_status endpoint using a GET request:


$ curl --request GET 'api.cerkl.com/v3/blast_status' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Retrieving Blasts

To get all of your organization’s Cerkl Blasts, use a GET request to hit our /blast endpoint:


$ curl --request GET 'api.cerkl.com/v3/blast' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

To retrieve a specific Blast, simply append the id (12345 in this example) of an existing Blast to the previous request URL to make use of our /blast/{id} endpoint:

Updating Blasts

To update an existing Blast, use the same URL pattern ending with the Blast’s id (12345 in our example) and make a PUT request to the /blast/{id} endpoint:


$ curl --request PUT 'api.cerkl.com/v3/blast/12345' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}' \
        --data-raw '{
            "template": {
                "version": "3.0",
                "data": [
                    {
                            "status": {
                                "id": 0
                            },
                            "blast_template": {
                                "id": 0
                            },
                            "blast_merge_fields": [
                                {
                                    "id": 0,
                                    "type": {
                                        "id": 0
                                    },
                                    "value": "string"
                                }
                            ],
                            "name": "string",
                            "reply_to_email": "string",
                            "reply_to_name": "string",
                            "subject": "string",
                            "message": "string",
                            "target_segments": [
                                {
                                    "id": 0
                                }
                            ],
                            "target_categories": [
                                {
                                    "id": 0
                                }
                            ],
                            "target_conditional": {
                                "id": 0
                            },
                            "date_scheduled_utc": "string"
                    }
                ]
            }
        }'

Deleting Blasts

To delete an existing Blast, simply make a DELETE request to the /blast/{id} endpoint using the Blast’s id value. If we stick with our Blast id = 12345 example, it should look something like this:


$ curl --request DELETE 'api.cerkl.com/v3/blast/12345' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Cerkl Insights

As your Cerkl News Digests are delivered, it can be helpful to understand how your Subscribers are interacting with the Content they are presented with. These insights are tracked both for the specific pieces of Content and also from the perspective of the Subscribers in your Audience, allowing you to comprehend which Content is most effective and/or which Subscribers are the most active with their personalized News Digests.

Content Insights


$ curl --request GET 'api.cerkl.com/v3//content_insights' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Subscriber Insights


$ curl --request GET 'api.cerkl.com/v3//subscriber_insights' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'

Subscriber Interests

As Subscribers interact with their News Digests, Cerkl begins to understand which types of Content they are most interested in. For example, if you are consistently reading pieces about Engineering (and they are properly tagged as such), then your Subscriber profile will reflect that. Using our /subscriber/{subscriber_id}/subscriber_interest endpoint with a GET request will return the categories the Subscriber with id == subscriber_id is most interested in.

If our example Subscriber has an id of 1001, that request looks like this:


$ curl --request GET 'api.cerkl.com/v3/subscriber/1001/subscriber_interest' \
        --header 'Authorization: Bearer {ACCESS_TOKEN}'
INFO
If you have any questions at all, don’t hesitate to reach to our team via email support@cerkl.com or use the chat bot in the bottom right-hand corner of any cerkl.com page for a quick answer.
Sections
SubscribersContentUnsubscribesSegmentsCategoriesBlastsInsights