/segment/lookup | Documentation

The SegmentLookupHandler class retrieves a list of segments for both specified user identifiers, and context for site groups provided in the request. It handles validation of user and context information, resolves identities for each site group, and performs segment lookups based on provided criteria.

For using this method as part of a Javascript integration, see the ready integration guide at Piano Audience segments helper function - getSegments() .

The user must be authenticated and have read permissions to the specified site group.

Request Parameters

The SegmentLookupRequest object accepts the following parameters:

Name	Type	Required	Description
`siteGroupIds`	Array of Strings	Yes	List of site group IDs to retrieve segments for.
`identity`	Object	No	Object of `identity` containing User identifier, and type of the user identifier for segment lookup (e.g., 'cx' for Cxense-specific identifier).
`identities`	Array of Objects	No	List of `identity`, each containing `type` and `id`.
`candidateSegmentIds`	Array of segment IDs	No	List of candidate segment IDs to consider for the lookup.
`responseFormat`	Enum	No	Format of the response (`cx`, `rtc`). Defaults to `cx`.
`shortIds`	boolean	No	If set the short ids will be included
`context`	Object	No	See `Context Object` below.

Identity Object Fields

Name	Type	Required	Description
`id`	String	Yes	The user identifier.
`type`	String	Yes	The type of the user identifier.

Context Object Fields

Name	Type	Required	Description
`url`	String	Yes	The url of the page to look up.
`siteId`	String	Yes	The site id for the url.

Response Structure

cx Format

Name	Type	Description
`segments`	Array of Objects	List of segments where the user is a member. Each object contains `id` and `type` and `shortId` (if it is requested) fields.

rtc Format

Name	Type	Description
`targeting`	Object	Contains the field `CxSegments` with an array of segment identifiers where the user is a member.

Examples

Bash

# Single lookup
$ python cx.py /segment/lookup '{"identity": {"id":"hvfufdee4dai1giaud", "type":"cx"}, "siteGroupIds":["92028378393"], "context":{"siteId": "site64", "url": "http://url.com"}}'
{
 "segments": [{
 "type": "traffic", "id": "8pbc50ol8ryj" 
 }, {
 "type": "contextual", "id": "8ctx50ual" 
 }]
}

# Provide candidate when checking whether a user is a member of a specific segment
$ python cx.py /segment/lookup '{"identity": {"id":"hvfufdee4dai1giaud", "type":"cx"}, "siteGroupIds":["92028378393"], "candidateSegmentIds":["8pbc50ol8ryj","123"]}'
{
 "segments": [{
 "type": "traffic", "id": "8pbc50ol8ryj"
 }]
}

# Single lookup when rtc enabled
$ python cx.py /segment/lookup '{"identity": {"id":"hvfufdee4dai1giaud", "type":"cx"}, "siteGroupIds":["92028378393"], "format": "rtc"}'
{
 "targeting":{
 "CxSegments": [
 "8pbc50ol8ryj",
 "8ctx50ualryj"
 ]
 }
}

$ python cx.py /segment/lookup '{"identity": {"id":"hvfufdee4dai1giaud", "type":"cx"}, "shortIds":true, "siteGroupIds":["92028378393"], "candidateSegmentIds":["8pbc50ol8ryj","123"]}'
{
 "segments": [{
 "type": "traffic", "id": "8pbc50ol8ryj", "shortId": "0" 
 }]
}

Last updated: May 13, 2025