Get Credentials

Get credentials

After signing in, you can create credentials that can be used to call the Platform APIs.

Segmentation Service API (1.0)

Download OpenAPI specification:Download

Adobe Experience Platform Segmentation Service provides a user interface and RESTful API that allows you to create audiences through segment definitions or other sources from your Real-Time Customer Profile data. These audiences are centrally configured and maintained on Platform, and are readily accessible by any Adobe solution. Use the Segmentation Service API to programmatically integrate the service's various functionalities into your experience application, providing RESTful endpoints for managing audiences, segment definitions, segment jobs, exports, schedules, and more.

Audiences

Audiences are a set of people, accounts, households, or other entities that share common characteristics and behaviors. This set can be generated either by using Platform or from external sources. More information about using this set of endpoints can be found in the audiences endpoint guide.

List audiences

Request
query Parameters
start
integer

A query parameter that specifies the starting offset for the audiences returned.

Example: start=4
limit
integer

A query parameter that specifies the total number of audiences returned per page.

Example: limit=20
sort
string

A query parameter that specifies the field to sort the results by. This is written in the format [attributeName]:[desc/asc]

Example: sort=updateTime:desc
property
string

A query parameter that specifies which audiences to return. The audiences returned must exactly match the attribute value given. This is written in the format property=[attributeName]==[attributeValue].

Example: property=property=audienceId==test-audience-id
name
string

A query parameter that filters for audiences that contain the string in the name. This value is case insensitive.

Example: name=Test
description
string

A query parameter that filters for audiences that contain the string in the description. This value is case insensitive.

Example: description=Test description
entityType
string

A query parameter that lets you filter the type of audience you're looking for.

Example: entityType=_xom.context.account
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

get/audiences
Response samples
application/json
{
  • "children": [
    ],
  • "_page": {
    },
  • "_links": {
    }
}

Create an audience

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json

The request body for creating an audience.

One of:
name
string

The ID of the audience.

profileInstanceId
string
description
string

A description of the audience.

type
string

A field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include SegmentDefinition and ExternalAudience.

object

The PQL expression for the audience.

object

The Experience Data Model (XDM) schema class name.

labels
Array of strings

Object-level data usage and attribute-based access control labels that are relevant to the audience.

Responses
201

Success

400

Error

post/audiences
Request samples
application/json

A sample body for creating an audience.

{
  • "name": "People who ordered in the last 30 days",
  • "profileInstanceId": "ups",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "type": "SegmentDefinition",
  • "expression": {
    },
  • "schema": {
    },
  • "labels": [
    ]
}
Response samples
application/json

A sample Platform-generated audience.

{
  • "id": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "schema": {
    },
  • "profileInstanceId": "ups",
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "sandbox": {
    },
  • "isSystem": false,
  • "name": "People who ordered in the last 30 days",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "expression": {
    },
  • "mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
  • "evaluationInfo": {
    },
  • "dataGovernancePolicy": {
    },
  • "creationTime": 1650374572000,
  • "updateEpoch": 1650374573,
  • "updateTime": 1650374573000,
  • "createEpoch": 1650374572,
  • "_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
  • "dependents": [ ],
  • "definedOn": [],
  • "dependencies": [ ],
  • "type": "SegmentDefinition",
  • "overridePerformanceWarnings": false,
  • "createdBy": "audiences@AdobeId",
  • "lifecycle": "active",
  • "labels": [
    ],
  • "namespace": "AEPSegments"
}

Retrieve an audience

Request
path Parameters
AUDIENCE_ID
required
string

The ID of the audience you want to retrieve.

Example: 60ccea95-1435-4180-97a5-58af4aa285ab
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

404

Not found

get/audiences/{AUDIENCE_ID}
Response samples
application/json

A sample Platform-generated audience.

{
  • "id": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "schema": {
    },
  • "profileInstanceId": "ups",
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "sandbox": {
    },
  • "isSystem": false,
  • "name": "People who ordered in the last 30 days",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "expression": {
    },
  • "mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
  • "evaluationInfo": {
    },
  • "dataGovernancePolicy": {
    },
  • "creationTime": 1650374572000,
  • "updateEpoch": 1650374573,
  • "updateTime": 1650374573000,
  • "createEpoch": 1650374572,
  • "_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
  • "dependents": [ ],
  • "definedOn": [],
  • "dependencies": [ ],
  • "type": "SegmentDefinition",
  • "overridePerformanceWarnings": false,
  • "createdBy": "audiences@AdobeId",
  • "lifecycle": "active",
  • "labels": [
    ],
  • "namespace": "AEPSegments"
}

Delete an audience

Request
path Parameters
AUDIENCE_ID
required
string

The ID of the audience you want to retrieve.

Example: 60ccea95-1435-4180-97a5-58af4aa285ab
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
204

Success

400

Error

403

Missing access permissions

404

Not found

delete/audiences/{AUDIENCE_ID}
Response samples
application/json
{ }

Update one or more attributes of an audience

Request
path Parameters
AUDIENCE_ID
required
string

The ID of the audience you want to patch.

Example: 60ccea95-1435-4180-97a5-58af4aa285ab
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json

A sample request body to update the PQL expression of the audience.

Array
op
string
path
string
object
Responses
201

Success

400

Error

404

Not found

patch/audiences/{AUDIENCE_ID}
Request samples
application/json

The following PATCH request will update the audience's workAddress.country to US.

[
  • {
    }
]
Response samples
application/json

A sample Platform-generated audience.

{
  • "id": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "schema": {
    },
  • "profileInstanceId": "ups",
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "sandbox": {
    },
  • "isSystem": false,
  • "name": "People who ordered in the last 30 days",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "expression": {
    },
  • "mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
  • "evaluationInfo": {
    },
  • "dataGovernancePolicy": {
    },
  • "creationTime": 1650374572000,
  • "updateEpoch": 1650374573,
  • "updateTime": 1650374573000,
  • "createEpoch": 1650374572,
  • "_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
  • "dependents": [ ],
  • "definedOn": [],
  • "dependencies": [ ],
  • "type": "SegmentDefinition",
  • "overridePerformanceWarnings": false,
  • "createdBy": "audiences@AdobeId",
  • "lifecycle": "active",
  • "labels": [
    ],
  • "namespace": "AEPSegments"
}

Update an audience

Request
path Parameters
AUDIENCE_ID
required
string

The ID of the audience you want to overwrite.

Example: 60ccea95-1435-4180-97a5-58af4aa285ab
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json

The request body to update the audience.

One of:
audienceId
string

The ID of the audience.

name
string

The name of the audience.

namespace
string

The namespace that the audience belongs to. Possible values include AAM, AAMSegments, AAMTraits, and AEPSegments.

description
string

A description of the audience.

type
string

A system-generated field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include SegmentDefinition and ExternalAudience.

lifecycleState
string

A Platform-maintained status to show the status of the audience. Possible values include draft, published, inactive, and archived.

datasetId
string

The dataset where the audience data can be found.

labels
Array of strings

Object-level data usage and attribute-based access control labels that are relevant to the audience.

Responses
201

Success

400

Error

404

Not found

500

Access control validation error

put/audiences/{AUDIENCE_ID}
Request samples
application/json

A sample request body for updating an audience's name.

{
  • "audienceId": "test-external-audience-id",
  • "name": "New externalSegment",
  • "namespace": "aam",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "type": "ExternalSegment",
  • "lifecycle": "published",
  • "datasetId": "6254cf3c97f8e31b639fb14d",
  • "labels": [
    ]
}
Response samples
application/json

A sample Platform-generated audience.

{
  • "id": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
  • "schema": {
    },
  • "profileInstanceId": "ups",
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "sandbox": {
    },
  • "isSystem": false,
  • "name": "People who ordered in the last 30 days",
  • "description": "This audience is generated to see people who ordered in the last 30 days.",
  • "expression": {
    },
  • "mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
  • "evaluationInfo": {
    },
  • "dataGovernancePolicy": {
    },
  • "creationTime": 1650374572000,
  • "updateEpoch": 1650374573,
  • "updateTime": 1650374573000,
  • "createEpoch": 1650374572,
  • "_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
  • "dependents": [ ],
  • "definedOn": [],
  • "dependencies": [ ],
  • "type": "SegmentDefinition",
  • "overridePerformanceWarnings": false,
  • "createdBy": "audiences@AdobeId",
  • "lifecycle": "active",
  • "labels": [
    ],
  • "namespace": "AEPSegments"
}

Retrieve multiple audiences

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

A sample request body to retrieve multiple audiences.

Array of objects
Responses
207

Success

400

Error

404

Not found

post/audiences/bulk-get
Request samples
application/json
{
  • "ids": [
    ]
}
Response samples
application/json
{
  • "results": {
    }
}

Estimates

Estimates provide statistical information on a segment definition, such as the projected audience size and confidence interval. More information about using this set of endpoints can be found in the previews and estimates endpoint guide.

Retrieve the results of an estimate job

Request
path Parameters
ESTIMATE_ID
required
string

The ID of the estimate job.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/estimate/{ESTIMATE_ID}
Response samples
application/json
{}

Export jobs

Export jobs are asynchronous processes that are used to persist audience members to datasets. More information about using this set of endpoints can be found in the export jobs endpoint guide.

List export jobs

Request
query Parameters
limit
integer

Limit the number of export jobs returned in the list.

offset
string

Offset the page of results returned, ordered by created time of resource.

status
string

Filter the export jobs returned by job status.

Enum: "NEW" "SUCCEEDED" "FAILED"
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

503

Service unavailable

get/export/jobs
Response samples
application/json
{
  • "records": [
    ],
  • "page": {
    },
  • "link": {
    }
}

Create an export job

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-profile-instance-id
string

The ID of the profile instance. Example: ups

Request Body schema: application/json
required
  • fields - [Optional] Column filters (comma-separated list of columns in dot notation). Limits the data fields to be included in the export to only those provided in this parameter. The same parameter is also available when creating a segment definition, therefore the fields in the segment definition may have already been filtered. Omitting this value will result in all fields being included in the exported data.
  • mergePolicy - [Optional] Specifies the merge policy to govern the exported data. Include this parameter when there are multiple segment definitions being exported. Omitting this value will cause the Export Service to use the merge policy provided by the segmentId or snapshotName.
    • id - The ID of the merge policy.
    • version - The specific version of the merge policy to use. Omitting this value will default to the most recent version.
  • filter - [Optional] Specifies one or more of the following filters to apply to the segment definition before export.
    • segments - [Optional] Specifies the segment definitions to export. Omitting this value will result in all data from all profiles being exported. Accepts an array of segment definitions, each containing the following fields:
      • segmentId - [Required if specifying segment definitions] Segment definition ID for profiles to be exported.
      • segmentNs - [Optional] The namespace of the segment definition for the given segmentId.
      • status - [Optional] An array of strings providing a status filter for the segmentID. By default, status will have the value ["realized", "existing"] which represents all profiles that fall into the segment definition at the current time. Possible values include: "realized", "existing", and "exited".
    • segmentQualificationTime - [Optional] Filter based on segment qualification time. The start time and/or end time can be provided.
      • startTime - [Optional] Segment qualification start time for a segment definition ID for a given status. It not provided, there will be no filter on the start time for a segment definition ID qualification. The timestamp must be provided in RFC 3339 format.
      • endTime - [Optional] Segment qualification end time for a segment definition ID for a given status. It not provided, there will be no filter on the end time for a segment definition ID qualification. The timestamp must be provided in RFC 3339 format.
    • fromIngestTimestamp - [Optional] Filters the resulting profiles to those that have been updated after the provided timestamp. Value is provided in RFC 3339 format. Supports greater_than operand.
    • emptyProfiles - [Optional] Boolean. Profiles can contain Profile records, ExperienceEvent records, or both. Profiles with no Profile records and only ExperienceEvent records are referred to as "emptyProfiles". To export all profiles in the Profile store, including the "emptyProfiles", set the value of "emptyProfiles" to true. If "emptyProfiles" is set to false, only profiles with Profile records in the store are exported. By default, if "emptyProfiles" attribute is not included, only profiles containing Profile records are exported.
  • additionalFields - [Optional] Additional profile fields that need to be exported.
    • eventList - Used if ExperienceEvents need to be exported with profiles.
      • fields - Comma-separated list of ExperienceEvent fields to be included in the export. If not provided, all ExperienceEvent fields are exported.
      • filter - Filters ExperienceEvents based on the parameters below. If not provided, all events corresponding to the resulting profiles will be exported.
        • fromIngestTimestamp - Filters ExperienceEvents to those that have been updated after the provided timestamp. This is not the event time itself but the ingestion time for the events. Value is provided in RFC 3339 format.
  • destination - [Required] Destination information for the exported data.
    • datasetId - [Required] The ID of the dataset where data is to be exported.
    • segmentPerBatch [Optional] A Boolean value that, if not provided, defaults to false. A value of false exports all segment definition IDs into a single batch ID. A value of true exports one segment definition ID into one batch ID.
  • schema.name - [Required] The name of the schema associated with the dataset where data is to be exported.
fields
string

The columns in which you can filter by. They are written as comma separated dot notation of the requested columns.

object (MergePolicyObject)

An object that describes the items within a merge policy.

object (Filter)

Array of filter values for Export Job to export Profiles.

object (AdditionalFields)

Additional fields that need to be exported.

object

The location where the exported data will be stored.

object

The schema name for the data.

Responses
200

Success

403

Missing access permissions

503

Service unavailable

post/export/jobs
Request samples
application/json
{
  • "fields": "identities.id,personalEmail.address",
  • "mergePolicy": {
    },
  • "filter": {
    },
  • "additionalFields": {
    },
  • "destination": {
    },
  • "schema": {
    }
}
Response samples
application/json
{
  • "id": 100,
  • "jobType": "BATCH",
  • "destination": {
    },
  • "fields": "identities.id,personalEmail.address",
  • "schema": {
    },
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "status": "SUCCEEDED",
  • "filter": {
    },
  • "additionalFields": {
    },
  • "mergePolicy": {
    },
  • "profileInstanceId": "ups",
  • "errors": [
    ],
  • "metrics": {
    },
  • "computeGatewayJobId": {
    },
  • "creationTime": 1538615973895,
  • "updateTime": 1538616233239,
  • "requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}

Retrieve an export job

Request
path Parameters
EXPORT_JOB_ID
required
string

The ID of the export job you want to retrieve.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/export/jobs/{EXPORT_JOB_ID}
Response samples
application/json
{
  • "id": 100,
  • "jobType": "BATCH",
  • "destination": {
    },
  • "fields": "identities.id,personalEmail.address",
  • "schema": {
    },
  • "imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
  • "status": "SUCCEEDED",
  • "filter": {
    },
  • "additionalFields": {
    },
  • "mergePolicy": {
    },
  • "profileInstanceId": "ups",
  • "errors": [
    ],
  • "metrics": {
    },
  • "computeGatewayJobId": {
    },
  • "creationTime": 1538615973895,
  • "updateTime": 1538616233239,
  • "requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}

Cancel or delete an export job

Request
path Parameters
EXPORT_JOB_ID
required
string

The ID of the export job you want to cancel or delete.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

delete/export/jobs/{EXPORT_JOB_ID}
Response samples
application/json
{
  • "status": true,
  • "message": "Export job has been marked for cancelling"
}

Previews

Previews provide paginated lists of qualifying profiles for a segment definition. More information about using this set of endpoints can be found in the previews and estimates endpoint guide

Create a preview job

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required
  • predicateExpression: The predicate expression that is to be evaluated.
  • predicateType: (Default: PQL) The only value that is available to use for this is PQL for now.
  • predicateModel: (Default: xdm.model.profile) The model against which this predicate is to be evaluated. Please note that 'touchpoint' is not treated as model as it can be associated with any of the models like profile.
  • graphType: The graph type that you want to get the cluster from. Possible values are "none" (perform no identity stitching) and "pdg" (perform identity stitching based on your private identity graph).
predicateExpression
string

The predicate expression that is to be evaluated.

predicateType
string

The predicate expression type. By default, this is PQL.

predicateModel
string

The model in which the predicate is evaluated against. By default, this value is "xdm.model.profile".

graphType
string

The graph type that you want to get the cluster from. If the value is pdg, identity stitching will be done based on your private identity graph. If the value is none, no identity stitching will be done.

Enum: "pdg" "none"
Responses
201

Success

403

Missing access permissions

503

Service unavailable

post/preview
Request samples
application/json
{
  • "predicateExpression": "xEvent.metrics.commerce.abandons.value > 0",
  • "predicateType": "pql/text",
  • "predicateModel": "_xdm.context.profile",
  • "graphType": "pdg"
}
Response samples
application/json
{
  • "previewQueryId": "4a45e853-ac91-4bb7-a426-150937b6af5c",
  • "state": "RUNNING",
  • "previewQueryStatus": "RUNNING",
  • "previewId": "MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg",
  • "previewExecutionId": 42
}

Retrieve the results of a preview job

Request
path Parameters
PREVIEW_ID
required
string

The ID of the preview job.

query Parameters
offset
string

The offset of the page.

Example: offset=offset=10200
limit
integer

The number of entries that should be present on a page. If not specified, this value will be 1000.

Example: limit=100
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/preview/{PREVIEW_ID}
Response samples
application/json
{
  • "page": { },
  • "link": "string",
  • "state": "string",
  • "results": [
    ]
}

Cancel or delete a preview job

Request
path Parameters
PREVIEW_ID
required
string

The ID of the preview job.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

delete/preview/{PREVIEW_ID}
Response samples
application/json
{
  • "status": true,
  • "message": "string"
}

Schedules

Create a recurring schedule to automatically run export jobs. A schedule can run at most once daily. More information about using this set of endpoints can be found in the schedules endpoint guide.

List schedules

Request
query Parameters
start
integer

Return results from a specific page offset. For example, start=3.

limit
integer

Limit response to a specific number of objects. Must be a positive number. For example, limit=10

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Responses
200

Success

403

Missing access permissions

500

Internal service error

503

Service unavailable

get/config/schedules
Response samples
application/json
{
  • "_page": {
    },
  • "children": [
    ]
}

Create a schedule

This endpoint is used to create a schedule, including specifying the time when the schedule should be triggered. Note that the scheduler is updated periodically (approximately every 30 minutes), so changes to a schedule may not go into effect immediately.

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Request Body schema: application/json
required
  • name: (Required) The name of schedule. Must be a string. - type: (Required) The job type in string format.
    • Supported types: batch_segmentation and export.
  • properties: (Required) An object containing additional properties related to the schedule. - properties.segments: (Required when type equals batch_segmentation) Using [\"*\"] ensures all segment definitions are included. - schedule: (Required) A string containing the job schedule. Jobs can only be scheduled to run once a day, meaning you cannot schedule a job to run more than once during a 24 hour period. The example shown (0 30 13 * * ?) means the job is triggered every day at 13:30:00 UTC. For more information, please review the cron expression format documentation. - state: (Optional) String containing the schedule state. Available values: active and inactive. Default value is inactive."
name
required
string

The name of the schedule being created.

type
required
string

The job type.

Value: "batch_segmentation"
required
object

schedule properties

schedule
required
string

A cron expression stating when the schedule should be triggered. Jobs can only be scheduled to run once a day, meaning you cannot schedule a job to run more than once during a 24 hour period. For more information, please review the cron expression format documentation.

state
string

The state of the schedule. If the schedule is inactive, it must be activated before it will be triggered.

Enum: "active" "inactive"
Responses
200

Success

400

Error

403

Missing access permissions

500

Internal service error

503

Service unavailable

post/config/schedules
Request samples
application/json
{
  • "name": "profile-default",
  • "type": "batch_segmentation",
  • "properties": {
    },
  • "schedule": "0 0 1 * * ?",
  • "state": "inactive"
}
Response samples
application/json
{
  • "id": "5e61e66e-e8b4-4a7b-8d41-70c74b0b981a",
  • "name": "profile-default",
  • "type": "batch_segmentation",
  • "schedule": "0 0 1 * * ?",
  • "state": "inactive",
  • "properties": {
    },
  • "createEpoch": 1234567890,
  • "updateEpoch": 1234567890
}

Retrieve a schedule

The scheduler is updated periodically (approximately every 30 minutes), so changes to a schedule may not go into effect immediately.

Request
path Parameters
SCHEDULE_ID
required
string

The ID of the schedule against which the operation is being performed.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/config/schedules/{SCHEDULE_ID}
Response samples
application/json
{
  • "id": "5e61e66e-e8b4-4a7b-8d41-70c74b0b981a",
  • "name": "profile-default",
  • "type": "batch_segmentation",
  • "schedule": "0 0 1 * * ?",
  • "state": "inactive",
  • "properties": {
    },
  • "createEpoch": 1234567890,
  • "updateEpoch": 1234567890
}

Delete a schedule

Request
path Parameters
SCHEDULE_ID
required
string

The ID of the schedule against which the operation is being performed.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Responses
204

Success

403

Missing access permissions

404

Not found

503

Service unavailable

delete/config/schedules/{SCHEDULE_ID}

Update a schedule

This endpoint is ued to update a schedule, including changing the trigger time or enabling/disabling the schedule. Note that the scheduler is updated periodically (approximately every 30 minutes), so changes to a schedule may not go into effect immediately.

Request
path Parameters
SCHEDULE_ID
required
string

The ID of the schedule against which the operation is being performed.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Request Body schema: application/json
required

Use JSON Patch formatting to update the schedule. Note: You must use an "add" operation to add or update the given "path" with the given "value".

Array
op
required
string

The patch operation you are performing.

Value: "add"
path
required
string

The path of the attribute that needs to be updated. This value can either be /state or /schedule, depending what you want to update.

value
required
string

The updated value for the field you want to update. If using the /state path, this value can either be active or inactive. If using the /schedule path, this will be the updated cron schedule.

Responses
204

Success

400

Error

403

Missing access permissions

429

Rate limit

500

Internal service error

503

Service unavailable

patch/config/schedules/{SCHEDULE_ID}
Request samples
application/json
[
  • {
    }
]

Segment definitions

Segment definitions include a Profile Query Language (PQL) statement that defines which profiles will be part of an audience. More information about using this set of endpoints can be found in the segment definitions endpoint guide.

List segment definitions

Request
query Parameters
start
integer <int64>

The page offset, as per created time of resource.

Example: start=109103839
limit
integer

The maximum size of the page.

Example: limit=10
page
integer

The page number.

sort
string

The parameters used to sort the results.

Example: sort=sort=name:asc,internalId:desc
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Responses
200

Success

403

Missing access permissions

503

Service unavailable

get/segment/definitions
Response samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "name": "People who ordered in the last 30 days",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "description": "Last 30 days",
  • "expression": {
    },
  • "schema": {
    },
  • "evaluationInfo": {
    },
  • "payloadSchema": "string",
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateTime": 0,
  • "updateEpoch": 0
}

Create a segment definition

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Request Body schema: application/json
required
  • name: The name of the segment definition. This value must be unique.
  • description: A description of the segment definition.
  • expression: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.
  • schema: - The schema class for the segment definition.
  • evaluationInfo: - An object that determines the type of segment definition that's created. If batch is set to true, it will be a segment definition evaluated using batch segmentation. If continuous is set to true, it will be a segment definition evaluated using streaming segmentation. If synchronous is set to true, it will be a segment definition evaluated using edge segmentation. By default, a segment definition evaluated using batch segmentation will be created.
name
required
string

The unique name for the segment definition.

description
string

An optional description to describe the segment definition.

profileInstanceId
string
required
object
object
required
object
payloadSchema
string
Responses
200

Success

400

Error

403

Missing access permissions

422

Already exists

503

Service unavailable

post/segment/definitions
Request samples
application/json
{
  • "name": "Sample segment definition",
  • "description": "Sample description",
  • "expression": {
    },
  • "evaluationInfo": {
    },
  • "schema": {
    },
  • "payloadSchema": "string"
}
Response samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "name": "Sample segment definition",
  • "description": "Sample description",
  • "expression": {
    },
  • "evaluationInfo": {
    },
  • "schema": {
    },
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateEpoch": 1579292094,
  • "updateTime": 1579292094000,
  • "payloadSchema": "string"
}

Retrieve a segment definition

Request
path Parameters
SEGMENT_ID
required
string

The ID of the segment definition.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/segment/definitions/{SEGMENT_ID}
Response samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "name": "People who ordered in the last 30 days",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "description": "Last 30 days",
  • "expression": {
    },
  • "schema": {
    },
  • "evaluationInfo": {
    },
  • "payloadSchema": "string",
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateTime": 0,
  • "updateEpoch": 0
}

Delete a segment definition

Request
path Parameters
SEGMENT_ID
required
string

The ID of the segment definition.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Responses
200

Success

403

Missing access permissions

503

Service unavailable

delete/segment/definitions/{SEGMENT_ID}
Response samples
application/json
{
  • "status": true,
  • "message": "string"
}

Overwrite a segment definition.

Request
path Parameters
SEGMENT_ID
required
string

The ID of the segment definition.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Request Body schema: application/json
required
  • name: The name of the segment definition. This value must be unique.
  • description: A description of the segment definition.
  • expression: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.
  • schema: - The schema class for the segment definition.
id
string
imsOrgId
string

The ID of the organization related to the segment definition.

name
required
string

A unique name for the segment definition.

mergePolicyId
string

The ID of the merge policy.

profileInstanceId
string

The ID of the profile instance provided.

description
string

A brief description about the segment definition.

required
object (Expression)

Information regarding the segment definition's expression.

required
object (SchemaClass)

The schema class.

object

An object that describes how the audience is evaluated.

payloadSchema
string
object
creationTime
integer <int64>

The timestamp, as unix time in milliseconds, for when the segment definition was created.

updateTime
integer <int64>

The timestamp, as unix time in milliseconds, for when the segment definition was last updated.

updateEpoch
integer <int64>

The timestamp, as unix time in seconds, for when the segment definition was last updated.

Responses
200

Success

400

Error

403

Missing access permissions

503

Service unavailable

patch/segment/definitions/{SEGMENT_ID}
Request samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "name": "People who ordered in the last 30 days",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "description": "Last 30 days",
  • "expression": {
    },
  • "schema": {
    },
  • "evaluationInfo": {
    },
  • "payloadSchema": "string",
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateTime": 0,
  • "updateEpoch": 0
}
Response samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "name": "People who ordered in the last 30 days",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "description": "Last 30 days",
  • "expression": {
    },
  • "schema": {
    },
  • "evaluationInfo": {
    },
  • "payloadSchema": "string",
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateTime": 0,
  • "updateEpoch": 0
}

Retrieve multiple segment definitions using multiple segment definition IDs

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

An array of the segment definition IDs that you are trying to retrieve.

Array of objects
Responses
207

Success

post/segment/definitions/bulk-get
Request samples
application/json
{
  • "ids": [
    ]
}
Response samples
application/json
{
  • "results": {
    }
}

Convert a segment definition

This endpoint converts a segment definition from pql/text to pql/json or from pql/json to pql/text.

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
Request Body schema: */*
required
  • name: The name of the segment definition. This value must be unique.
  • description: A description of the segment definition.
  • expression: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.
  • schema: - The schema class for the segment definition.
id
string
imsOrgId
string

The ID of the organization related to the segment definition.

name
required
string

A unique name for the segment definition.

mergePolicyId
string

The ID of the merge policy.

profileInstanceId
string

The ID of the profile instance provided.

description
string

A brief description about the segment definition.

required
object (Expression)

Information regarding the segment definition's expression.

required
object (SchemaClass)

The schema class.

object

An object that describes how the audience is evaluated.

payloadSchema
string
object
creationTime
integer <int64>

The timestamp, as unix time in milliseconds, for when the segment definition was created.

updateTime
integer <int64>

The timestamp, as unix time in milliseconds, for when the segment definition was last updated.

updateEpoch
integer <int64>

The timestamp, as unix time in seconds, for when the segment definition was last updated.

Responses
200

Success

400

Error

409

Conflict

429

Too many requests

503

Service unavailable

post/segment/conversion
Response samples
application/json
{
  • "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
  • "imsOrgId": "{ORG_ID}",
  • "name": "People who ordered in the last 30 days",
  • "mergePolicyId": "5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b",
  • "profileInstanceId": "ups",
  • "description": "Last 30 days",
  • "expression": {
    },
  • "schema": {
    },
  • "evaluationInfo": {
    },
  • "payloadSchema": "string",
  • "dataGovernancePolicy": {
    },
  • "creationTime": 0,
  • "updateTime": 0,
  • "updateEpoch": 0
}

Segment jobs

Segment jobs process previously established segment definitions to generate an audience. More information about using this set of endpoints can be found in the segment jobs endpoint guide.

List all segment job requests

Request
query Parameters
snapshot.name
string

The snapshot name.

Example: snapshot.name=inUS
start
integer <int64>

The page offset, as per the created time of the resource.

Example: start=2
limit
integer

The maximum number of segment jobs retrieved per page.

Example: limit=10
status
string

The job status.

Example: status=PROCESSING
sort
string

Used to order the segment jobs. Is written in the format [attributeName]:[desc|asc]

Example: sort=creationTime:desc
property
string

Used to get exact matches within an attribute in the segment job. Is written in the format [arrayTypeAttributeName]~[objectKey]==[value]

Example: property=segments~segmentId==workInCanada
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

A unique ID that can be used to track a request.

Example: q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA
Responses
200

Success

403

Missing access permissions

500

Internal server error

503

Service unavailable

get/segment/jobs
Response samples
application/json
{
  • "_page": {
    },
  • "children": {
    },
  • "_links": {
    }
}

Create a segment job request

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-profile-instance-id
string

The ID of the Profile Instance. Example: ups

Example: ups
x-request-id
string

A unique ID that can be used to track a request. Example: q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA

Example: q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA
Request Body schema: application/json
required

List of segment jobs. Each should be in JSON format.

Array
segmentId
required
string

The ID of the segment definition.

Responses
200

Success

400

Error

403

Missing access permissions

429

Rate limit

500

Internal service error

503

Service unavailable

post/segment/jobs
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "id": "468eeefd-95a2-45a1-8bfc-b806dafce7ee",
  • "imsOrgId": "{IMG_ORG}",
  • "sandbox": {
    },
  • "profileInstanceId": "{PROFILE_INSTANCE}",
  • "status": "PROCESSING",
  • "batchId": "65e18145-a5e8-4993-94f3-c70fadaa1fef",
  • "computeJobId": 1,
  • "computeGatewayJobId": "c3505859-d256-45d0-a6f3-c25f8f8508f5",
  • "creationTime": 1233456789000,
  • "updateTime": 1233456789000,
  • "segments": [
    ],
  • "errors": [
    ],
  • "metrics": {
    },
  • "requestId": "cc3d3381-8682-41d4-93bd-566e378624d3",
  • "modelName": "_xdm.context.profile",
  • "_links": {
    }
}

Retrieve a segment job request

Request
path Parameters
SEGMENT_JOB_ID
required
string

The ID of the segment job request.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Responses
200

Success

403

Missing access permissions

404

Not found

503

Service unavailable

get/segment/jobs/{SEGMENT_JOB_ID}
Response samples
application/json
{
  • "id": "468eeefd-95a2-45a1-8bfc-b806dafce7ee",
  • "imsOrgId": "E95186D65A28ABF00A495D82@AdobeOrg",
  • "sandbox": {
    },
  • "profileInstanceId": "ups",
  • "source": "scheduler",
  • "status": "PROCESSING",
  • "batchId": "65e18145-a5e8-4993-94f3-c70fadaa1fef",
  • "computeJobId": 11037,
  • "computeGatewayJobId": "9ea97b25-a0f5-410e-ae87-b2d85e58f399",
  • "segments": [
    ],
  • "metrics": {
    },
  • "requestId": "4e538382-dbd8-449e-988a-4ac639ebe72b-1573203600264",
  • "schema": {
    },
  • "properties": {
    },
  • "_links": {
    },
  • "updateTime": 1573204395000,
  • "creationTime": 1573203600535,
  • "updateEpoch": 1573204395
}

Cancel a segment job request

Request
path Parameters
SEGMENT_JOB_ID
required
string

The ID of the segment job request.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-request-id
string

An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request.

Responses
204

Success

403

Missing access permissions

404

Not found

503

Service unavailable

delete/segment/jobs/{SEGMENT_JOB_ID}

Retrieve multiple segment jobs using multiple job IDs

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

Content-Type
required
string

The type of content being sent in the body of the request. Should be 'application/json'.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

An array of the segment jobs IDs that you are trying to retrieve.

Array of objects
Responses
207

Success

post/segment/jobs/bulk-get
Request samples
application/json
{
  • "ids": [
    ]
}
Response samples
application/json
{
  • "results": {
    }
}

List search count results

This endpoint is used to retrieve a list of search count results, which is queried across all namespaces.

Request
query Parameters
schema.name
required
string

The schema class value associated with the search objects. Currently, only _xdm.context.segmentdefinition is supported.

Example: schema.name=_xdm.context.segmentdefinition
s
string

The search query, based on the Lucene query syntax.

Example: s=name:test
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-ups-search-version
string

The version of the Search API used. The only supported version is 1.0.

Example: 1.0
Responses
200

Success

403

Missing access permissions

503

Service unavailable

get/search/namespaces
Response samples
application/json
{
  • "namespaces": [
    ],
  • "totalCount": "3",
  • "status": {
    }
}

List full-text indexed objects

This endpoint retrieves a list of all full text indexed objects contained within a namespace.

Request
query Parameters
schemaClass
required
string

The schema class value associated with the search objects. Currently, only _xdm.context.segmentdefinition is supported.

Example: schemaClass=_xdm.context.segmentdefinition
namespace
required
string

The namespace you want to search within.

Example: namespace=AAMTraits
s
string

The search query, based on the Lucene query syntax.

Example: s=name:test
entityId
string

The ID of the folder you want to search for external segment definitions in.

Example: entityId=fastMotorcyclesFolderid
limit
number

The number of search results to return per page. The maximum is 50.

Example: limit=10
page
number

The offset of the page. The first page starts at 0.

Example: page=2
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-ups-search-version
string

The version of the Search API used. The only supported version is 1.0.

Example: 1.0
Responses
200

Success

403

Missing access permissions

503

Service unavailable

get/search/entities
Response samples
application/json
{
  • "entities": [
    ],
  • "page": {
    },
  • "status": {
    }
}

Retrieve a search object's taxonomic information

Show the search object's organization

Request
query Parameters
schema.name
required
string

The name of the schema being searched.

Example: schema.name=_xdm.context.segmentdefinition
namespace
required
string

namespace

Example: namespace=AAMTraits
entityId
required
string

The ID of the object you want to get structural information about.

Example: entityId=porshe911_id
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
required
string

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

x-ups-search-version
string

The version of the Search API used.

Example: 1.0
Responses
200

Success

403

Missing access permissions

503

Service unavailable

get/search/taxonomy
Response samples
application/json
{
  • "taxonomy": [
    ],
  • "status": {
    }
}