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:

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):

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.

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

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.