Lists, filters and search
GET /organizations, GET /contacts and GET /deals share one query language. MCP’s query_records takes the
same filters as filters: [{ field, op, value }].
Filters
Section titled “Filters”filter[<field>][<op>]=<value>Several filters are ANDed. Use curl -g (or encode [ and ]) so curl does not treat the brackets as a glob.
| Op | Meaning |
|---|---|
eq, ne |
Equal, not equal. ne also matches NULL |
lt, lte, gt, gte |
Ranges |
in, nin |
Comma list (in=lead,prospect). nin also matches NULL |
contains |
Case-insensitive substring |
is_null |
true or false |
lt_or_null |
Less than, or never set: the right op for “not contacted in 48 hours, or never” |
Plain lt skips records whose value is NULL, so lastContactedAt lt now-48h misses leads nobody ever contacted.
Filterable fields
Section titled “Filterable fields”Every scalar field of the resource, plus:
tag(eq/in, case-insensitive). Repeatingfilter[tag][eq]means “all these tags”.customFields.<key>(below).- Contacts:
organizationId. Deals:organizationId,contactId,stage.outcome(open,won,lost).
Unknown field or op → 400 FILTER_INVALID with details.allowed.
Relative times
Section titled “Relative times”For timestamp fields: now, today (start of today in the account timezone) and start_of_month, each optionally
shifted by ±N minutes (m), hours (h), days (d) or weeks (w): now-48h, now-30m, today-7d,
start_of_month+1d. Days and weeks from today and start_of_month are calendar days. A bare date on a
timestamp field means local midnight. Date fields (expectedCloseOn) take YYYY-MM-DD or a relative time.
In a URL, write + as %2B (today%2B14d).
Custom fields
Section titled “Custom fields”| Key | Ops |
|---|---|
| Undefined key | eq, in, compared as text (5 matches 5 and "5") |
Defined number, date |
eq ne lt lte gt gte in nin is_null lt_or_null, compared as numbers or dates |
Defined boolean |
eq ne is_null |
Defined select |
eq ne in nin is_null |
Defined text, url, email |
eq ne in nin contains is_null |
A value stored with the wrong type (the string "57" in a number field, "2026-02-30" in a date field) counts as
NULL in typed filters. Only active definitions type a key. See custom fields.
sort=<field>:asc|desc[:nulls_first|nulls_last][,<field>:…]Default updatedAt:desc. NULLs sort last for asc and first for desc unless you say otherwise. Defined custom
fields sort too (sort=customFields.obsolescenceScore:desc; numbers and dates typed, the rest as text); undefined
keys cannot sort (400 FILTER_INVALID).
Status, paging, sparse fields, q
Section titled “Status, paging, sparse fields, q”- Only
activerecords are listed unless you filter onstatus. Shortcut:status=active|archived|all. page,perPage(≤ 100, default 50).fields=id,name,email: only those fields in each item (idalways). Saves bandwidth and tokens.q: free-text match. Organizations on name, domain and email; contacts on name and email; deals on name.
Examples
Section titled “Examples”# leads and prospects not contacted in 48 hours, or nevercurl -sg "https://api.mety.ai/api/v1/contacts?filter[lifecycle][in]=lead,prospect&filter[doNotContact][eq]=false&filter[lastContactedAt][lt_or_null]=now-48h&sort=lastContactedAt:asc:nulls_first" \ -H "Authorization: Bearer $METY_KEY"
# open deals that have not changed stage in 14 dayscurl -sg "https://api.mety.ai/api/v1/deals?filter[stage.outcome][eq]=open&filter[stageEnteredAt][lt]=now-14d&sort=stageEnteredAt:asc" \ -H "Authorization: Bearer $METY_KEY"
# organizations tagged both "inmobiliaria" and "gipuzkoa"curl -sg "https://api.mety.ai/api/v1/organizations?filter[tag][eq]=inmobiliaria&filter[tag][eq]=gipuzkoa" \ -H "Authorization: Bearer $METY_KEY"
# the worst websites first, by a defined custom fieldcurl -sg "https://api.mety.ai/api/v1/organizations?filter[customFields.obsolescenceScore][gte]=50&filter[customFields.province][eq]=Gipuzkoa&sort=customFields.obsolescenceScore:desc" \ -H "Authorization: Bearer $METY_KEY"Global search
Section titled “Global search”curl -s "https://api.mety.ai/api/v1/search?q=acme&types=organization,contact,deal&limit=10" \ -H "Authorization: Bearer $METY_KEY"{ "data": [{ "type": "organization", "id": "…", "title": "Acme Inmobiliaria", "subtitle": "…", "status": "active" }] }q needs at least 2 characters. Prefix and substring matches on organization name, domain and email, contact
name and email, and deal name. limit is 1–50 (default 10). Search before you create.