Custom Segment Filtering

Using Custom Segments in Post Reports

Clients may opt to send information based on custom segments in the CreativeX platform. These configurations are client-specific and cannot be documented here. They are supported on post reports only and are not available for core asset reports.

Step 1: Retrieve available dimensions

Before creating a report, call the dimensions endpoint to discover which custom segments are configured for your organization.

GET /reports/posts/dimensions

The response includes a custom_segments array listing each available dimension and its valid values:

JSON

{
  "brands": ["..."],
  "markets": ["..."],
  "channels": ["..."],
  "custom_segments": [
    {
      "name": "Region",
      "values": ["North America", "EMEA", "APAC"]
    },
    {
      "name": "Product Line",
      "values": ["Product A", "Product B", "Product C"]
    }
  ]
}

If your organization has not configured any custom segments, custom_segments will be an empty array.

Step 2: Create a report with custom segment filters

Pass a custom_segments array in the request body when creating a post report. Each entry specifies a dimension name and an array of values to filter by.

POST /reports/posts

JSON

{
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "brands": ["Acme Corp"],
  "custom_segments": [
    {
      "name": "Region",
      "values": ["North America", "EMEA"]
    },
    {
      "name": "Product Line",
      "values": ["Product A"]
    }
  ]
}

The custom_segments parameter is optional. When omitted, the report includes posts from all custom segment values.

Validation

Dimension names and values are validated against your organization's configured segments. The API returns a 400 error if:

• A name does not match any of your organization's configured custom segment dimensions
• A values entry is not a valid value for the specified dimension

Use the dimensions endpoint to retrieve the valid names and values before submitting a request.

Response

Custom segment values are returned on each post record in the custom_segments field as an array of name/value pairs:

JSON

{
  "creativex_post_id": 123456,
  "brand": "Acme Corp",
  "market": "United States",
  "channel": "Facebook",
  "custom_segments": [
    { "name": "Region", "value": "North America" },
    { "name": "Product Line", "value": "Product A" }
  ]
}