menu
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.
Endpoint
POST https://api.sendstreak.com/v2/accounts/{accountId}/contacts/search
All v2 endpoints require a bearer token - see Authentication.
Path parameters
| Parameter | Type | Description |
|---|---|---|
accountId | string | The account the request is scoped to. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
start | integer | Zero-based offset of the first item to return. Default: 0. |
limit | integer | Maximum number of items to return. Clamped to 100. Default: 25. |
Request body
Audience selection spec for contact search.
| Field | Type | Required | Description |
|---|---|---|---|
attributes | array of objects | no | Attribute conditions a contact must match; conditions are combined with AND. |
attributes[].slug | string | no | Attribute slug to test - see the attribute metas endpoint. |
attributes[].operator | string | no | Comparison operator, e.g. equality or range checks depending on the attribute type. |
attributes[].value | any | no | Value to compare against; its type follows the attributeās type. |
includeUnsubscribed | boolean | yes | Include unsubscribed contacts in the results. |
topicId | string | no | Restrict to contacts not unsubscribed from this announcement topic. |
Response
A page of matching contacts (with resolved attributes).
{
"start": 0,
"limit": 25,
"items": [
{
"_id": "665f0a2b1c9d440012ab34cd",
"email": "[email protected]",
"createDate": "2026-07-07T09:30:00.000Z",
"hardBounced": "2026-07-07T09:30:00.000Z",
"unsubscribeDate": "2026-07-07T09:30:00.000Z",
"topicUnsubscriptions": [
"6651dd2e4f9b110014ab90cd"
]
}
]
}
Errors
| Status | Description |
|---|---|
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 example
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": "signup",
"operator": "equals",
"value": "professional"
}
],
"includeUnsubscribed": false,
"topicId": "6651dd2e4f9b110014ab90cd"
}'