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.