API docs by Redocly

Segment Manager Public API (1.0)

Segment Templates

List available templates

Lists all templates available for segment creation. Returned templated definitions include the required user input which will then be interpolated into the templated attributes and segment definition in order to create the needed resources. See the applyTemplate endpoint for more details on how to.

Authorizations:
httpAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or reuse segment from template

Creates or reuses a segment and the respective attributes that feed it by applying user input to the template with the ID specified in the endpoint's path. The network ID is also required in order for the segment to be associated with the Kevel Native Segments destination for that network.

The response contains the ID of the created or reused segment, along with the template that was used.

Authorizations:
httpAuth
path Parameters
id
required
string

The template ID to use for segment creation.

Request Body schema: application/json
networkId
required
integer <int32>

The network ID to associate the segment with in the respective KevelNativeSegments destination.

advertiserId
required
integer <int64>

The ID of the advertiser creating this segment.

required
object (Map_Json)

Map of user inputs to interpolate into the template. These will be validated in accordance with the expected type attributed to the input in the template's definition.

Responses

Request samples

Content type
application/json
{
  • "networkId": 10000,
  • "advertiserId": 2712478,
  • "userInputs": {
    }
}

Response samples

Content type
application/json
{
  • "segmentId": 0,
  • "template": {
    }
}

List most recent template instantiations

Lists up to the 10 most recent instantiations for the given template, ordered by application time (most recent first). Each entry includes the resulting segment and attributes (with their content-hash IDs and whether they were reused) and the user inputs provided.

Authorizations:
httpAuth
path Parameters
id
required
string

The template ID whose instantiations to list.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

External Segments

List segments

Returns a paginated list of segment metadata.

Authorizations:
httpAuth
query Parameters
networkId
required
integer <int32>

The network ID associated with the segments.

region
required
string

The region associated with the segments.

pageSize
integer <int32> <= 50
Default: 20

Maximum number of segments to return per page.

page
integer <int32>
Default: 1

The page number, starting at 1.

Responses

Response samples

Content type
application/json
{
  • "page": 1,
  • "pageSize": 1,
  • "segments": [
    ]
}

Create segment

Creates a segment from metadata and attaches it to the network's "Kevel - Native Segments" destination. The destination is identified by the network ID and region supplied in the request body.

Authorizations:
httpAuth
Request Body schema: application/json
networkId
required
integer <int32>

The network ID where the segment will be created.

region
required
string

The region for the network, for example eu-central-1.

name
required
string

The segment name, which must be unique.

category
string

The optional segment category. Defaults to an empty string when omitted.

description
string

The optional segment description. Defaults to an empty string when omitted.

isStatic
boolean

Whether to mark this segment as static. If a segment is static, its membership should be stable over time. Only static segments can be made available in Forecast. Defaults to false when omitted.

Responses

Request samples

Content type
application/json
{
  • "networkId": 12345,
  • "region": "eu-central-1",
  • "name": "Core Customers",
  • "category": "Loyalty",
  • "description": "Top 20% revenue customers",
  • "isStatic": true
}

Response samples

Content type
application/json
{
  • "id": "es_02f28ebe",
  • "name": "Core Customers",
  • "category": "Loyalty",
  • "description": "Top 20% revenue customers",
  • "isStatic": true,
  • "networkId": 12345,
  • "region": "eu-central-1"
}

Retrieve segment

Returns metadata for a segment.

Authorizations:
httpAuth
path Parameters
id
required
string

The segment ID.

Responses

Response samples

Content type
application/json
{
  • "id": "es_02f28ebe",
  • "name": "Core Customers",
  • "category": "Loyalty",
  • "description": "Top 20% revenue customers",
  • "isStatic": true,
  • "networkId": 12345,
  • "region": "eu-central-1"
}

Delete segment

Deletes the segment.

Authorizations:
httpAuth
path Parameters
id
required
string

The segment ID.

Responses

Response samples

Content type
application/json
{
  • "error": "Malformed or invalid credentials"
}

Update segment

Updates segment metadata. Omitted fields retain their values.

Authorizations:
httpAuth
path Parameters
id
required
string

The segment ID.

Request Body schema: application/json
name
string

The new segment name, which must be unique.

category
string

The new segment category.

description
string

The new segment description.

isStatic
boolean

Whether to mark this segment as static.

Responses

Request samples

Content type
application/json
{
  • "name": "Core Customers",
  • "category": "Loyalty",
  • "description": "Top 20% revenue customers",
  • "isStatic": true
}

Response samples

Content type
application/json
{
  • "id": "es_02f28ebe",
  • "name": "Core Customers",
  • "category": "Loyalty",
  • "description": "Top 20% revenue customers",
  • "isStatic": true,
  • "networkId": 12345,
  • "region": "eu-central-1"
}

Add or remove segment memberships

Adds or removes a set of user memberships in segments. Unknown users are implicitly created for add operations, and removing a non-member is an idempotent no-op. The response reports an outcome for every membership operation and uses HTTP 200 even when individual edges fail.

The total number of membership edits, calculated as the number of entries in memberships, must not exceed 50.

Authorizations:
httpAuth
Request Body schema: application/json
action
required
string
Enum: "add" "remove"

The membership operation: either add or remove.

Array of objects (MembershipEntry)

User in segment memberships to add or remove. The total membership edits count is capped at 50.

Responses

Request samples

Content type
application/json
{
  • "action": "add",
  • "memberships": [
    ]
}

Response samples

Content type
application/json
{
  • "action": "add",
  • "results": [
    ]
}

Check user segment membership

Returns whether a user is a member of the specified segment.

Authorizations:
httpAuth
path Parameters
id
required
string

The segment ID.

query Parameters
userIdType
required
string

The type of user ID.

userId
required
string

The user ID.

Responses

Response samples

Content type
application/json
{
  • "userId": "11d4c22e42c8f61feaba154683dea407b101cfd90987dda9e342843263ca420a",
  • "userIdType": "email_sha256",
  • "segmentId": "es_02f28ebe",
  • "isMember": true
}

List a user's segments

Returns the segment IDs associated with a user.

Authorizations:
httpAuth
query Parameters
userIdType
required
string

The type of user ID.

userId
required
string

The user ID.

networkId
required
integer <int32>

The network ID associated with the segments.

region
required
string

The region associated with the segments.

Responses

Response samples

Content type
application/json
{
  • "userId": "11d4c22e42c8f61feaba154683dea407b101cfd90987dda9e342843263ca420a",
  • "userIdType": "email_sha256",
  • "segments": [
    ]
}