Skip to content

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 }].

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.

Every scalar field of the resource, plus:

  • tag (eq/in, case-insensitive). Repeating filter[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.

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).

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).

  • Only active records are listed unless you filter on status. Shortcut: status=active|archived|all.
  • page, perPage (≤ 100, default 50).
  • fields=id,name,email: only those fields in each item (id always). Saves bandwidth and tokens.
  • q: free-text match. Organizations on name, domain and email; contacts on name and email; deals on name.
Terminal window
# leads and prospects not contacted in 48 hours, or never
curl -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 days
curl -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 field
curl -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"
Terminal window
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.