Audience Segments

Audience Segments

The audience segment APIs allow users to fetch all unique audience segments created, deleted or replaced under a particular Sub-Account, Connection or Batch.

Get by Sub-Account

This API can be used to fetch unique audience segments under a sub-account.

GET /es/v2/segments/account/<sub_account_id>

Query parameters

?type=created (default) | deleted | replaced
&pageSize=100
&page=1

Response:

{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}

Attributes:

Attribute	Description	Possible Values
segmentName	Name of the Audience Segment
segmentId	Unique id of the Audience segment
date	Date of creation / delete / replace	YYYY-MM-DD format
accountId	ID of the sub-account in which this segment was created or deleted or replaced.	UUID (16-character identifier)
connectionId	ID of the connection in which this segment was created or deleted or replaced.	UUID (16-character identifier)
batchId	ID of the batch in which this segment was created or deleted or replaced.	UUID (32-character identifier)
pageSize	Maximum number of segments to return in a single API call. Default: 100 Max Size: 1000	Integer (e.g., 10, 100 etc..)
page	Current page number	Integer (e.g., 1,2, 3, etc.)
totalPages	Total number of pages	Integer (e.g., 1, 2, 3, etc.)
totalRecords	Total number of records (segments) across all pages	Integer (e.g., 0, 10, 1000 etc..)

Sample Curl::

curl --location '<host>/es/v2/segments/account/9c4e0bbf84211a81' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-2144-d54d4be743fe'

Get by Connection

This API can be used to fetch unique audience segments under a given connection.

GET /es/v2/segments/connection/<connection_id>

Query parameters

?type=created (default) | deleted | replaced
&pageSize=100
&page=1

Response:

{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}

Attributes:

Attribute	Description	Possible Values
segmentName	Name of the Audience Segment
segmentId	Unique id of the Audience segment
date	Date of creation / delete / replace	YYYY-MM-DD format
accountId	ID of the sub-account in which this segment was created or deleted or replaced.	UUID (16-character identifier)
connectionId	ID of the connection in which this segment was created or deleted or replaced.	UUID (16-character identifier)
batchId	ID of the batch in which this segment was created or deleted or replaced.	UUID (32-character identifier)
pageSize	Maximum number of segments to return in a single API call. Default: 100 Max Size: 1000	Integer (e.g., 10, 100 etc..)
page	Current page number	Integer (e.g., 1,2, 3, etc.)
totalPages	Total number of pages	Integer (e.g., 1, 2, 3, etc.)
totalRecords	Total number of records (segments) across all pages	Integer (e.g., 0, 10, 1000 etc..)

Sample Curl::

curl --location '<host>/es/v2/segments/connection/fccc1c8423c11d' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-2144-d54d4be743fe'

Get by Batch

This API can be used to fetch unique audience segments under a given batch (transfer)

GET /es/v2/segments/batch/<batch_id>

Query parameters

?type=created (default) | deleted | replaced
&pageSize=100
&page=1

Response:

{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}

Attributes:

Attribute	Description	Possible Values
segmentName	Name of the Audience Segment
segmentId	Unique id of the Audience segment
date	Date of creation / delete / replace	YYYY-MM-DD format
accountId	ID of the sub-account in which this segment was created or deleted or replaced.	UUID (16-character identifier)
connectionId	ID of the connection in which this segment was created or deleted or replaced.	UUID (16-character identifier)
batchId	ID of the batch in which this segment was created or deleted or replaced.	UUID (32-character identifier)
pageSize	Maximum number of segments to return in a single API call. Default: 100 Max Size: 1000	Integer (e.g., 10, 100 etc..)
page	Current page number	Integer (e.g., 1,2, 3, etc.)
totalPages	Total number of pages	Integer (e.g., 1, 2, 3, etc.)
totalRecords	Total number of records (segments) across all pages	Integer (e.g., 0, 10, 1000 etc..)

Sample Curl::

curl --location '<host>/es/v2/segments/batch/22bb77079c084d0c984635611f999994' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-8344-214d4be743fe'

Get directly from Platform

This API can be used to fetch an audience list directly from the configured connector platform.

The API enables retrieval of segments based on:

• MadConnect Sub Account ID (mandatory)

• Ad Account ID (mandatory)

• Segment Name (optional)

• Segment ID (optional)

• Connector ID (mandatory)

Additionally, the API will only return segments matching the connector’s integration type (e.g., Customer File / Custom Audience).

Note:

• API will only fetch data if Connector is configured

• MadConnect does NOT store connector secrets

• Secrets are stored in the customer-managed Snowflake account or on a deployed cloud account. Secrets are retrieved dynamically at runtime

GET /es/v2/segments/direct

Query parameters

?subAcountId=<string> // sub account ID
?&adAccountId=<string> // Advertiser account ID
&connectorId=<string> // Connector ID
&segmentName=<string> // Name of the segment to filter - platform dependent
&segmentId=<string> // Id of the segment to filer - platform dependent
&pageToken=<string> // page token or index
&pageSize=50 // size of the page, default: 50; max:200

Response:

{
 "statusCode": 200,
 "statusMessage": "Request executed successfully",
 "response": {
   "segments": [
     {
       "segmentId": "<string>",
       "segmentName": "string>",
       "adAccountId": "<string>",
       "connectorId": "<string>",
       "platform": "<string>",
       "creationDate": "<string>",
       "updateDate": "<string>",
       "numUsers": 0,
       "status": "<string>",
       "statusMessage": "<string>",
       "type": "<string>"
     }
   ],
   "pageSize": 0,
   "nextPageToken" : "<string>",
   "hasMore" : <boolean>
 }
}

Attributes:

Attribute	Type	Description
segmentId	string	Unique segment identifier
segmentName	string	Segment name
adAccountId	string	Ad account ID
connectorId	string	Connector identifier
platform	string	Derived from connector metadata
creationDate	datetime	Created timestamp e.g. 2026-03-18T15:15:24Z
updateDate	datetime	Last updated timestamp e.g. 2026-03-18T15:15:24Z (returned if available in destination platform)
numUsers	integer	Audience size (returned if available in destination platform)
status	string	Segment status
statusMessage	string	Segment status message (platform-specific)

Sample Curl:

Fetch All Segments

GET /es/v2/segments/direct?accountId=acc_123&adAccountId=456&connectorId=ab123123789

Filter by Segment Name

GET /es/v2/segments/direct?accountId=acc_123&adAccountId=meta_456&connectorId=conn_789&segmentName=customer

Fetch by Segment ID

GET /es/v2/segments/direct?accountId=acc_123&adAccountId=meta_456&connectorId=conn_789&segmentId=seg_123&pageSize=100

Meta Ads - Not Supported Fields

Field	Description
segmentId	Filter on segment id is not supported