Audience Contact Search: Sample Requests

Use the Audience Contact Search API to search for contacts within a specific audience, such as a list, CCG, UDT, or segment. You can filter contacts using multiple conditions, sort the results, paginate through matching contacts, or retrieve only the total count.

The API is synchronous. The response contains the search results or count directly.

Search Contacts in an Audience

When to use: Use this when you want to retrieve contacts belonging to a specific audience and apply one or more filters.
What changes: Set audience_type, define filtering_criteria, and specify the fields you want returned in output.fields.
Best for: Finding a targeted set of contacts within an audience.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

📘
Good to know

filtering_criteria defines the conditions used to find matching contacts.

output.pagination and output.fields are required when retrieving contact data.

output.pagination.page starts at 1.

output.pagination.limit has a minimum value of 10.

Search Contacts Using Multiple Conditions

When to use: Use this when you want to find contacts that match multiple conditions, such as identified contacts with a specific attribute.
What changes: Add multiple objects inside condition_details and use condition_operator to determine how those conditions are combined.
Best for: Targeted searches, such as finding premium customers in a particular location.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        },
        {
          "field": "CUSTOMER_TYPE",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Premium"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "MOBILE",
      "CUSTOMER_TYPE"
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

📘
Good to know
condition_operator supports and and or. Use and when all conditions must match, and or when any condition can match.

Search Contacts Using or Conditions

When to use: Use this when contacts can match any one of multiple conditions.
What changes: Set condition_operator to or.
Best for: Searches where a contact can qualify based on different values, such as customers from multiple customer types.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "or",
      "condition_details": [
        {
          "field": "CUSTOMER_TYPE",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Premium"
          ]
        },
        {
          "field": "CUSTOMER_TYPE",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Enterprise"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "CUSTOMER_TYPE"
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

Search Contacts with a Specific Attribute Value

When to use: Use this when you want to find contacts based on a custom contact attribute.
What changes: Set field_category to attribute and provide the attribute name in field.
Best for: Finding contacts based on information such as customer type, location, membership status, or other configured attributes.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "STATE",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Maharashtra"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "MOBILE",
      "STATE"
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

📘
Good to know
The attribute name used in field must correspond to an attribute available for the account. Use the exact attribute name configured in your account.

Search Contacts with Pattern Matching

When to use: Use this when you want to find contacts whose field values begin with a specific value.
What changes: Use the startswith operation.
Best for: Searches such as finding contacts whose email or another supported field starts with a particular value.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "EMAIL",
          "field_category": "attribute",
          "operation": "startswith",
          "value": [
            "john"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "MOBILE"
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

Get the Count of Matching Contacts

When to use: Use this when you only need to know how many contacts match your search criteria and do not need the contact records.
What changes: Set the count mode to return only the total number of matching records.
Best for: Audience size checks, validation before campaigns, reporting, or determining how many contacts meet a condition.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "CUSTOMER_TYPE",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Premium"
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": true
  }
}

📘
Good to know
When count mode is enabled, pagination, fields, and sorting are ignored.

Search Contacts with Sorting and Pagination

When to use: Use this when you need to retrieve contacts in a specific order and process the results page by page.
What changes: Define output.sorting and output.pagination.
Best for: Applications that display or process contacts in batches.

{
  "audience_type": "list",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        }
      ]
    }
  ],
  "output": {
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ],
    "sorting": [
      {
        "field": "created_at",
        "direction": "desc"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    }
  }
}

Notes for Audience Contact Search endpoint

page has a minimum value of 1.
limit has a minimum value of 10.
direction supports asc and desc.
Sorting is ignored when count mode is enabled.