DocumentationExperience PlatformSegmentation Service Guide

Segment definitions endpoint

Last update: Fri Sep 06 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

Adobe Experience Platform allows you to create segment definitions that define a group of specific attributes or behaviors from a group of profiles. A segment definition is an object that encapsulates a query written in Profile Query Language (PQL). Segment definitions are applied to profiles to create audiences. This object (segment definition) 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.

This guide provides information to help you better understand segment definitions and includes sample API calls for performing basic actions using the API.

Getting started

The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.

Retrieve a list of segment definitions list

You can retrieve a list of all segment definitions for your organization by making a GET request to the /segment/definitions endpoint.

API format

The /segment/definitions endpoint supports several query parameters to help filter your results. While these parameters are optional, their use is strongly recommended to help reduce expensive overhead. Making a call to this endpoint with no parameters will retrieve all segment definitions available for your organization. Multiple parameters can be included, separated by ampersands (&).

GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}

Query parameters

A list of available query parameters.
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
Parameter Description Example
start Specifies the starting offset for the segment definitions returned. start=4
limit Specifies the number of segment definitions returned per page. limit=20
page Specifies which page the results of segment definitions will start from. page=5
sort Specifies which field to sort the results by. Is written in the following format: [attributeName]:[desc/asc]. sort=updateTime:desc
evaluationInfo.continuous.enabled Specifies if the segment definition is streaming-enabled. evaluationInfo.continuous.enabled=true

Request

The following request will retrieve the last two segment definitions posted within your organization.

A sample request to retrieve a list of segment definitions.
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions?limit=2 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 200 with a list of segment definitions for the specified organization as JSON.

A sample response when retrieving a list of segment definitions.
code language-json 
{
    "segments": [
        {
            "id": "3da8bad9-29fb-40e0-b39e-f80322e964de",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1573253640000,
            "baselineTime": 1574327114,
            "updateEpoch": 1575588309,
            "updateTime": 1575588309000
        },
        {
            "id": "ca763983-5572-4ea4-809c-b7dff7e0d79b",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "imsOrgId": "{ORG_ID}",
            "name": "test segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1561073779000,
            "baselineTime": 1574327114,
            "updateEpoch": 1574327114,
            "updateTime": 1574327114000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

Create a new segment definition create

You can create a new segment definition by making a POST request to the /segment/definitions endpoint.

IMPORTANT
Segment definitions created through the API cannot be edited using Segment Builder.

API format

POST /segment/definitions

Request

When creating a new segment definition, you can create it in either the pql/text or pql/json format.

Using pql/text
accordion
A sample request to create a segment definition.
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "workAddress.country = \"US\""
        },
        "evaluationInfo": {
            "batch": {
                "enabled": true
            },
            "continuous": {
                "enabled": false
            },
            "synchronous": {
                "enabled": false
            }
        },
        "schema": {
            "name": "_xdm.context.profile"
        }
    }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2
Property Description
name A unique name by which to refer to the segment definition.
description (Optional) A description of the segment definition you are creating.
expression An entity that contains fields information about the segment definition.
expression.type Specifies the expression type. Currently, only “PQL” is supported.
expression.format Indicates the structure of the expression in value. Supported values include pql/text and pql/json.
expression.value An expression that conforms to the type indicated in expression.format.
evaluationInfo (Optional) The type of segment definition you are creating. If you want to create a batch segment, set evaluationInfo.batch.enabled to be true. If you want to create a streaming segment, set evaluationInfo.continuous.enabled to be true. If you want to create an edge segment, set evaluationInfo.synchronous.enabled to be true. If left empty, the segment definition will be created as a batch segment.
schema The schema associated with the entities in the segment. Consists of either an id or name field.
Using pql/json
accordion
A sample request to create a segment definition.
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "profileInstanceId": "ups",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/json",
            "value": "{\"nodeType\":\"fnApply\",\"fnName\":\"=\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"a\",\"object\":{\"nodeType\":\"parameterReference\",\"position\":1}},{\"nodeType\":\"fieldLookup\",\"fieldName\":\"b\",\"object\":{\"nodeType\":\"parameterReference\",\"position\":1}}]}"
        },
        "evaluationInfo": {
            "batch": {
                "enabled": true
            },
            "continuous": {
                "enabled": false
            },
            "synchronous": {
                "enabled": false
            }
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string"
    }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2
Property Description
name A unique name by which to refer to the segment definition.
description (Optional) A description of the segment definition you are creating.
evaluationInfo (Optional) The type of segment definition you are creating. If you want to create a batch segment, set evaluationInfo.batch.enabled to be true. If you want to create a streaming segment, set evaluationInfo.continuous.enabled to be true. If you want to create an edge segment, set evaluationInfo.synchronous.enabled to be true. If left empty, the segment definition will be created as a batch segment.
schema The schema associated with the entities in the segment. Consists of either an id or name field.
expression An entity that contains fields information about the segment definition.
expression.type Specifies the expression type. Currently, only “PQL” is supported.
expression.format Indicates the structure of the expression in value.
expression.value An expression that conforms to the type indicated in expression.format.

Response

A successful response returns HTTP status 200 with details of your newly created segment definition.

A sample response when creating a segment definition.
code language-json 
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}
table 0-row-2 1-row-2 2-row-2
Property Description
id A system-generated ID of your newly created segment definition.
evaluationInfo An object that indicates what type of evaluation the segment definition will undergo. It can be batch, streaming (also known as continuous), or edge (also known as synchronous) segmentation.

Retrieve a specific segment definition get

You can retrieve detailed information about a specific segment definition by making a GET request to the /segment/definitions endpoint and providing the ID of the segment definition you wish to retrieve in the request path.

API format

GET /segment/definitions/{SEGMENT_ID}
Parameter
Description
{SEGMENT_ID}
The id value of the segment definition you want to retrieve.

Request

A sample request to retrieve a segment definition.
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 200 with detailed information about the specified segment definition.

A sample response when retrieving a segment definition.
code language-json 
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2
Property Description
id A system-generated read-only ID of the segment definition.
name A unique name by which to refer to the segment definition.
schema The schema associated with the entities in the segment. Consists of either an id or name field.
expression An entity that contains fields information about the segment definition.
expression.type Specifies the expression type. Currently, only “PQL” is supported.
expression.format

Indicates the structure of the expression in value. Currently, the following format is supported:

  • pql/text: A textual representation of a segment definition, according to the published PQL grammar. For example, workAddress.stateProvince = homeAddress.stateProvince.
expression.value An expression that conforms to the type indicated in expression.format.
description A human readable description of the definition.
evaluationInfo An object that indicates what type of evaluation, batch, streaming (also known as continuous), or edge (also known as synchronous), the segment definition will undergo.

Bulk retrieve segment definitions bulk-get

You can retrieve detailed information about multiple specified segment definitions by making a POST request to the /segment/definitions/bulk-get endpoint and providing the id values of the segment definitions in the request body.

API format

POST /segment/definitions/bulk-get

Request

A sample request when using the bulk get endpoint.
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions/bulk-get \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "ids": [
            {
                "id": "54669488-03ab-4e0d-a694-37fe49e32be8"
            },
            {
                "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05"
            }
        ]
    }'
table 0-row-2 1-row-2
Property Description
ids An array that contains objects that state the IDs of the segment definitions you want to retrieve.

Response

A successful response returns HTTP status 207 with the requested segment definitions.

A sample response when using the bulk get endpoint.
code language-json 
{
    "results": {
        "54669488-03ab-4e0d-a694-37fe49e32be8": {
            "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "profileInstanceId": "ups",
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        },
        "4afe34ae-8c98-4513-8a1d-67ccaa54bc05": {
            "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "profileInstanceId": "ups",
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        }

    }
}
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2
Property Description
id A system-generated read-only ID of the segment definition.
name A unique name by which to refer to the segment definition.
schema The schema associated with the entities in the segment. Consists of either an id or name field.
expression An entity that contains fields information about the segment definition.
expression.type Specifies the expression type. Currently, only “PQL” is supported.
expression.format

Indicates the structure of the expression in value. Currently, the following format is supported:

  • pql/text: A textual representation of a segment definition, according to the published PQL grammar. For example, workAddress.stateProvince = homeAddress.stateProvince.
expression.value An expression that conforms to the type indicated in expression.format.
description A human readable description of the definition.
evaluationInfo An object that indicates what type of evaluation, batch, streaming (also known as continuous), or edge (also known as synchronous), the segment definition will undergo.

Delete a specific segment definition delete

You can request to delete a specific segment definition by making a DELETE request to the /segment/definitions endpoint and providing the ID of the segment definition you wish to delete in the request path.

NOTE
A segment definition that is used in a destination activation cannot be deleted.

API format

DELETE /segment/definitions/{SEGMENT_ID}
Parameter
Description
{SEGMENT_ID}
The id value of the segment definition you want to delete.

Request

A sample request to delete a segment definition.
code language-shell 
curl -X DELETE https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 200 with no message.

Update a specific segment definition

You can update a specific segment definition by making a PATCH request to the /segment/definitions endpoint and providing the ID of the segment definition you wish to update in the request path.

API format

PATCH /segment/definitions/{SEGMENT_ID}
Parameter
Description
{SEGMENT_ID}
The id value of the segment definition you want to update.

Request

The following request will update the work address country from the USA to Canada.

NOTE
Since this API call replaces the content of the segment definition, please ensure all the fields you want to keep are included as part of the request body.
A sample request to update a segment definition.
code language-shell 
curl -X PATCH https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "name": "Updated people who ordered in the last 30 days",
    "profileInstanceId": "ups",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "schema": {
        "name": "_xdm.context.profile"
    },
    "payloadSchema": "string",
    "creationTime": 0,
    "updateTime": 0,
    "updateEpoch": 0
}'

Response

A successful response returns HTTP status 200 with details of your newly updated segment definition.

A sample response when updating a segment definition.
code language-json 
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "Updated people who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579295340,
    "updateTime": 1579295340000
}

Convert segment definition

You can convert a segment definition between pql/text and pql/json or pql/json to pql/text by making a POST request to the /segment/conversion endpoint.

API format

POST /segment/conversion

Request

The following request will change the segment definition’s format from pql/text to pql/json.

A sample request to convert the segment definition.
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ups/segment/conversion \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "profileInstanceId": "ups",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "workAddress.country = \"US\""
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string"
    }'

Response

A successful response returns HTTP status 200 with details of your newly converted segment definition.

A sample response when converting the segment definition.
code language-json 
{
    "imsOrgId": "6A29340459CA8D350A49413A@AdobeOrg",
    "sandbox": {
        "sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/json",
        "value": "{\"nodeType\":\"fnApply\",\"fnName\":\"=\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"country\",\"object\":{\"nodeType\":\"fieldLookup\",\"fieldName\":\"workAddress\",\"object\":{\"nodeType\":\"parameterReference\",\"position\":1}}},{\"nodeType\":\"literal\",\"literalType\":\"String\",\"value\":\"US\"}]}"
    }
}

Next steps

After reading this guide you now have a better understanding of how segment definitions work. For more information on creating a segment, please read the creating a segment tutorial.

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871