Create a segment definition using the Segmentation Service API

This document provides a tutorial for developing, testing, previewing, and saving a segment definition using the Adobe Experience Platform Segmentation Service API.

For information on how to build segment definitions using the user interface, please see the Segment Builder guide.

Getting started

This tutorial requires a working understanding of the various Adobe Experience Platform services involved in creating segment definitions. Before beginning this tutorial, please review the documentation for the following services:

The following sections provide additional information that you will need to know in order to successfully make calls to the Platform APIs.

Reading sample API calls

This tutorial provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Gather values for required headers

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All requests that contain a payload (POST, PUT, PATCH) require an additional header:

Develop a segment definition

The first step in segmentation is to define a segment definition. A segment definition is an object that encapsulates a query written in Profile Query Language (PQL). This object is also called a PQL predicate. PQL predicates define the rules for the segment definition based on conditions related to any record or time series data you supply to Real-Time Customer Profile. See the PQL guide for more information on writing PQL queries.

You can create a new segment definition by making a POST request to the /segment/definitions endpoint in the Segmentation API. The following example outlines how to format a definition request, including what information is required in order for a segment definition to be defined successfully.

For a detailed explanation on how to define a segment definition, please read the segment definition developer guide.

Estimate and preview an audience estimate-and-preview-an-audience

As you develop your segment definition, you can use the estimate and preview tools within Real-Time Customer Profile to view summary-level information to help ensure you are isolating the expected audience. Estimates provide statistical information on a segment definition, such as the projected audience size and confidence interval. Previews provide paginated lists of qualifying profiles for a segment definition, allowing you to compare the results against what you expect.

By estimating and previewing your audience, you can test and optimize your PQL predicates until they produce a desireable result, where they can then be used in an updated segment definition.

There are two required steps to preview or get an estimate of your segment definition:

How estimates are generated

As data enabled for Real-Time Customer Profile is ingested into Platform, it is stored within the Profile data store. When the ingestion of records into the Profile store increases or decreases the total profile count by more than 5%, a sampling job is triggered to update the count. If the profile count does not change by more than 5%, the sampling job will run automatically on a weekly basis.

The way in which the sample is triggered depends on the type of ingestion being used:

The sample size depends on the overall number of entities in your Profile store. These sample sizes are represented in the following table:

Estimates generally run over 10-15 seconds, beginning with a rough estimate and refining as more records are read.

Create a preview job

You can create a new preview job by making a POST request to the /preview endpoint.

Detailed instructions on creating a preview job can be found in the previews and estimates endpoints guide.

View an estimate or preview

Estimate and preview processes are run asynchronously as different queries can take different lengths of time to complete. Once a query has been initiated, you can use API calls to retrieve (GET) the current state of the estimate or preview as it progresses.

Using the Segmentation Service API, you can look up a preview job’s current state by its ID. If the state is “RESULT_READY”, you can view the results. To look up a preview job’s current state, please read the section on retrieving a preview job section in the previews and estimates endpoints guide. To look up an estimate job’s current state, please read the section on retrieving an estimate job in the previews and estimates endpoints guide.

Next steps

Once you have developed, tested, and saved your segment definition, you can create a segment job to build an audience using the Segmentation Service API. See the tutorial on evaluating and accessing segment results for detailed steps on how to accomplish this.