Search contacts by audience filter

Searches contacts with an audience filter - the same attribute-based segmentation the dashboard uses for campaign targeting - and returns the matches with resolved attributes, paginated.

POST/v2/accounts/{accountId}/contacts/search

Base URL https://api.sendstreak.com. All v2 endpoints require a bearer token - see Authentication.

Path parameters

accountIdstringrequired

The account the request is scoped to.

Query parameters

startintegeroptional

Zero-based offset of the first item to return. Default: 0.

limitintegeroptional

Maximum number of items to return. Clamped to 100. Default: 25.

Request body

Audience selection spec for contact search.

attributesarray of objectsoptional

Attribute conditions a contact must match; conditions are combined with AND.

slugstringrequired

Attribute slug to test - see the attribute metas endpoint.

operatorone of: exists, not_exists, true, false, s_equal, s_not_equal, contains, not_contains, n_equal, n_not_equal, greater_than, greater_than_equal, less_than, less_than_equal, after, before, d_equal, d_not_equalrequired

Comparison to apply. The s_/n_/d_ prefixes select string, number and date comparison; pick the family that matches the attribute’s type.

valueanyoptional

Value to compare against. Its type is dictated by the operator: send an empty string for exists, not_exists, true and false; a number for the n_ and greater_/less_than operators; a date for after, before, d_equal and d_not_equal; a string for the rest.

includeUnsubscribedbooleanrequired

Include unsubscribed contacts in the results.

topicIdstringoptional

Restrict to contacts not unsubscribed from this announcement topic.

Response

A page of matching contacts (with resolved attributes).

Errors

400

The request body or parameters failed validation.

401

Missing or invalid token, or the token is not authorized for this account/user.

See Errors and rate limits for what error responses look like.

curl --location --request POST 'https://api.sendstreak.com/v2/accounts/YOUR_ACCOUNT_ID/contacts/search' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "attributes": [
    {
      "slug": "plan",
      "operator": "s_equal",
      "value": "professional"
    }
  ],
  "includeUnsubscribed": false,
  "topicId": "6651dd2e4f9b110014ab90cd"
}'
const res = await fetch('https://api.sendstreak.com/v2/accounts/YOUR_ACCOUNT_ID/contacts/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDSTREAK_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "attributes": [
      {
        "slug": "plan",
        "operator": "s_equal",
        "value": "professional"
      }
    ],
    "includeUnsubscribed": false,
    "topicId": "6651dd2e4f9b110014ab90cd"
  })
});
import os, requests

res = requests.post(
    'https://api.sendstreak.com/v2/accounts/YOUR_ACCOUNT_ID/contacts/search',
    headers={'Authorization': f"Bearer {os.environ['SENDSTREAK_TOKEN']}"},
    json={
        "attributes": [
            {
                "slug": "plan",
                "operator": "s_equal",
                "value": "professional"
            }
        ],
        "includeUnsubscribed": False,
        "topicId": "6651dd2e4f9b110014ab90cd"
    },
)

response200application/json
{
  "start": 0,
  "limit": 25,
  "items": [
    {
      "_id": "665f0a2b1c9d440012ab34cd",
      "email": "[email protected]",
      "createDate": "2026-07-07T09:30:00.000Z",
      "hardBounced": "2026-07-07T09:30:00.000Z",
      "complaintDate": "2026-07-07T09:30:00.000Z",
      "unsubscribeDate": "2026-07-07T09:30:00.000Z",
      "topicUnsubscriptions": [
        "6651dd2e4f9b110014ab90cd"
      ]
    }
  ]
}