Contacts: Search
Query Contacts
Find contacts with any mix of list, status, tags, custom fields, engagement and dates. You describe who you want; the server picks the index.
https://g.sendcorex.com/v1/contactscommand: query_contactsNeeds the contact:read scope on your API key.
The server measures every indexed condition in where, scans the most selective one and checks each contact against the whole where. You never choose an index.
Arguments
whereobjectoptionalThe conditions, combined with AND. Leave it out (or send
{}) to get every contact. See thewherereference below.sortstring | objectoptionalA field name or
{ "field": "<name>" }. See Sorting below.e.g.
"open_rate"limitnumberoptionalPage size, from 1 to 1000. Defaults to 50.
cursorstringoptionalThe
next_cursorof the previous page. Send it with the samewhereandsort.selectstring[]optionalReturn only these parts of each contact, for example
["status", "fields.plan", "stats.open_count"].emailalways comes back. Without it you get the whole contact.
Quick start
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "query_contacts",
args: {
where: {
list: "customers",
sendable: true,
tags: {
has: "vip",
none: [
"churn"
]
},
fields: {
plan: {
in: [
"pro",
"business"
]
},
age: {
gte: 25,
lte: 40
}
},
last_open_at: {
within_days: 30
}
},
sort: "open_rate",
limit: 100
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Response
{
"type": "SUCCESS",
"results": [
{
"command": "query_contacts",
"id": "0",
"type": "SUCCESS",
"took_ms": 14,
"data": {
"contacts": [
{
"email": "ana@acme.com",
"domain": "acme.com",
"first_name": "Ana",
"last_name": "Costa",
"phone": null,
"company": "Acme",
"locale": "pt-BR",
"timezone": "America/Sao_Paulo",
"source": "checkout",
"status": "subscribed",
"status_reason": null,
"status_at": "2026-10-13T06:05:08.323Z",
"created_at": "2026-10-13T06:05:08.323Z",
"updated_at": "2026-10-14T09:12:40.118Z",
"tags": [
"customer",
"vip"
],
"lists": {
"customers": {
"subscribed": true,
"sendable": true,
"added_at": "2026-10-13T06:05:08.323Z",
"unsubscribed_at": null
}
},
"fields": {
"plan": "pro",
"age": 31,
"city": "São Paulo"
},
"stats": {
"sent_count": 12,
"open_count": 7,
"click_count": 2,
"bounce_count": 0,
"complaint_count": 0,
"open_rate": 0.58,
"click_rate": 0.17,
"first_open_at": "2026-10-13T08:41:02.000Z",
"last_open_at": "2026-10-14T21:03:55.000Z",
"last_click_at": "2026-10-14T21:04:10.000Z",
"last_sent_at": "2026-10-14T20:58:31.000Z"
}
}
],
"has_more": true,
"next_cursor": "eyJkIjoidGFnOnZpcCJ9",
"plan": {
"driver": "tag:vip",
"examined": 412,
"keys_only": false,
"ms": {
"scan": 4,
"fetch": 9,
"filter": 1,
"total": 14
}
}
}
}
]
}Response fields
contactsThe matching contacts. Whole contacts, or only the parts you asked for with
select.has_more / next_cursorPagination. While
has_moreistrue, sendnext_cursorascursorwith the samewhereandsort.plan.driverThe index the server picked to scan, for example
tag:viporlist:customers.plan.examinedHow many index entries were read to fill this page.
plan.keys_onlytruewhen the page was answered from the index alone, without loading the contacts.plan.msTime spent scanning, fetching, filtering and in total, in milliseconds.
The where object
Every key is optional and they all have to match. Text, enum options and tags ignore case and accents.
email"ana@acme.com". Reads that one contact directly.search"jo sil". Every word must be the start of a first name, last name, company or email word.status"subscribed", a list like["bounced", "complained"],{ "in": [...] }or{ "not": "subscribed" }.list"customers", or{ "in": ["a", "b"] }for members of any of them.sendabletrue. Withlist: subscribed to that list and with statussubscribed. Withoutlist: statussubscribed.tags{ "has": "vip" },{ "all": [...] },{ "any": [...] },{ "none": [...] }. They can be combined.domain"gmail.com"or{ "in": [...] }.fields{ "plan": "pro" },{ "age": { "gte": 25 } },{ "plan": { "in": [...] } },{ "city": { "contains": "paul" } },{ "company": { "exists": true } }. The field must exist.sent_count, open_count, click_count, bounce_count, complaint_count, open_rate, click_rateA number, or
{ "gte", "gt", "lte", "lt", "eq" }. Rates go from 0 to 1.created_at, first_open_at, last_open_at, last_click_at, last_sent_at{ "within_days": 30 },{ "after": "2026-01-01" },{ "before": "..." },{ "never": true }or{ "exists": true }.campaign_opened, campaign_clickedA campaign id. Contacts who opened or clicked that campaign.
An unknown key, or a field that does not exist, fails the command with INVALID_ARGS instead of silently matching nothing.
Operators for custom fields
Every custom field is indexed on its own, so these filters stay fast on large lists.
Equal{ "plan": "pro" }. Text and enum values ignore case and accents. On amulti_enumfield, it matches contacts that have that option.in{ "plan": { "in": ["pro", "business"] } }. Any of the values.gte, gt, lte, lt, eqRanges on
numberanddatefields. Dates acceptYYYY-MM-DDor ISO.containsPart of a
textvalue, ignoring case and accents.existstruefor contacts that have a value,falsefor those that do not.
Sorting
Each sort field has a fixed direction. Sorting by a custom field or a date only returns contacts that have a value: last_open_at returns only people who opened at least once.
emailA to Z.
fields.<key>Ascending. Not available for
multi_enumfields.sent_count, open_count, click_count, open_rate, click_rateHighest first.
created_at, last_open_at, last_click_at, last_sent_atMost recent first.
Pagination
Each call reads at most 20,000 index entries. When it hits that ceiling before filling the page, it returns fewer contacts (sometimes none) with has_more: true. Keep going while has_more is true; do not stop on an empty page.
Node.js
const where = { list: 'customers', sendable: true };
const emails = [];
let cursor;
do {
const [result] = await call({
command: 'query_contacts',
args: { where, select: ['email'], limit: 1000, ...(cursor ? { cursor } : {}) },
});
emails.push(...result.data.contacts.map((c) => c.email));
cursor = result.data.has_more ? result.data.next_cursor : null;
} while (cursor);call is any helper that posts { commands: [...] } to /v1/contacts and returns results, as in Run Commands.
More examples
Request body
{
"commands": [
{
"command": "query_contacts",
"id": "inactive",
"args": {
"where": {
"list": "customers",
"last_open_at": {
"never": true
},
"created_at": {
"before": "2026-07-01"
}
}
}
},
{
"command": "query_contacts",
"id": "bounced",
"args": {
"where": {
"status": [
"bounced",
"complained"
]
},
"select": [
"status",
"status_reason"
]
}
},
{
"command": "query_contacts",
"id": "search",
"args": {
"where": {
"search": "ana acme"
},
"limit": 10
}
}
]
}Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- CMD
MISSING_SCOPEThe API key does not have the scope this command needs. The other commands in the request still run.
- CMD
INVALID_ARGSA required argument is missing or invalid: email, field value, enum option, where key, list id…
- CMD
INVALID_CURSORThe cursor is malformed or belongs to another query or account.
- CMD
INTERNALServer error. The detail is only written to the server log.