Use the below sample use case to find identified contacts that belong to list 15, return their email, mobile number, and city, show 10 contacts at a time, and show the newest contacts first.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        },
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [
            15
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "sorting": [
      {
        "field": "created_at",
        "direction": "desc"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    },
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

Search Contacts by List

When to use: Use this when you want to find contacts that belong to a specific list.
What changes: Set field to list_id, field_category to audience, and use the equals operation.
Best for: Finding contacts belonging to a specific audience list.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [15]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "sorting": [
      {
        "field": "created_at",
        "direction": "desc"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10
    },
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

Search Contacts by Email or Identity

When to use: Use this when you want to find a specific contact using their email address or identity.
What changes: Set field to email or identity, set field_category to config, and use the equals operation.
Best for: Looking up an individual contact when you know their email address or identity.

By Email

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_details": [
        {
          "field": "email",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "[email protected]"
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

By Identity

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_details": [
        {
          "field": "identity",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "[email protected]"
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

Search Contacts by Attribute

When to use: Use this when you want to find contacts based on a contact attribute.
What changes: Set field_category to attribute, provide the attribute name in field, and specify the required operation and value.
Best for: Finding contacts based on information such as city, customer type, age, or another configured attribute.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_details": [
        {
          "field": "CITY",
          "field_category": "attribute",
          "operation": "equals",
          "value": [
            "Mumbai"
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "fields": [
      "contact_id",
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

Search Contacts Using Multiple Conditions

When to use: Use this when you want to narrow down contacts using more than one condition.

What changes: Add multiple objects to condition_details and use condition_operator to combine the conditions.

Best for: Searches such as finding identified contacts that belong to a specific list.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        },
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [
            15
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "fields": [
      "EMAIL",
      "MOBILE",
      "CITY"
    ]
  }
}

Search and Get Contact Count

When to use: Use this when you only need to know how many contacts match the specified filtering criteria.
What changes: Set get_count to true.
Best for: Audience sizing, reporting, eligibility checks, and dashboards.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_details": [
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [
            15
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": true,
    "fields": [
      "EMAIL"
    ]
  }
}

Search Contacts With Pagination and Sorting

When to use: Use this when your search can return a large number of contacts and you need the results in a specific order.
What changes: Add pagination and sorting inside output, then specify page, limit, field, and direction.
Best for: Batch processing, CRM synchronization, exports, and applications that process contacts page by page.

{
  "filtering_criteria_operator": "or",
  "filtering_criteria": [
    {
      "condition_details": [
        {
          "field": "list_id",
          "field_category": "audience",
          "operation": "equals",
          "value": [
            15
          ]
        }
      ]
    }
  ],
  "output": {
    "get_count": false,
    "sorting": [
      {
        "field": "created_at",
        "direction": "desc"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 100
    },
    "fields": [
      "contact_id",
      "EMAIL",
      "MOBILE"
    ]
  }
}

Notes for Search Contacts endpoint

get_count must be set to false when you want contact records in the response.
When get_count is true, the API returns the count of matching records instead of contact details.
Sorting and pagination are ignored when get_count is true.
The supported operation values defined in the OpenAPI specification include equals, startswith, not_equals, greater_than_or_equal_to, greater_than, not_in, less_than, ends_with, is_not_null, and is_null.