Find contacts

crm_find_contacts · Reads only · Markdown

Finds contacts by name, email, company or phone, by filters on any field or tag, or by a saved segment, one page at a time.

Free*

*Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads.

Show me every trade customer we haven't heard from since the summer.

Your agent callscrm_find_contactsFree*

The example business is Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. The reply is the one the tool really gives.

With these arguments

{
  "tag": "trade",
  "filters": [
    {
      "field": "lifecycle_stage",
      "op": "eq",
      "value": "customer"
    },
    {
      "field": "last_seen",
      "op": "lt",
      "value": "2026-07-01"
    }
  ]
}

What comes back

{
  "contacts": [
    {
      "id": 4107,
      "email": "clara@neumann-gastroplanung.example",
      "name": "Clara Neumann",
      "title": "Kitchen planner",
      "company": "Neumann Gastroplanung",
      "company_id": 4105,
      "phone": "",
      "location": "",
      "lifecycle_stage": "customer",
      "outreach_status": null,
      "notes": "",
      "tags": [
        "trade"
      ],
      "custom_fields": {},
      "archived": false,
      "updated_at": "2026-10-14T08:00:00+00:00"
    }
  ],
  "count": 1,
  "total": 1,
  "next_offset": null
}

Use it when

A list of people is needed: everyone tagged trade, all customers in Hamburg, leads not seen since the summer.

For one quick lookup from a name, email, phone or domain, use crm_search.
For the same list as a CSV file, use crm_export.

What it does

Search the CRM by name, email, company or phone, or by filters on any field, tag or custom field, or by a saved segment. Returns a page of contacts (most recently seen first unless `sort` says otherwise), the total, and next_offset for the next page.

What comes back

A page of contacts (id, email, name, title, company, phone, location, lifecycle stage, notes, tags, custom fields, archived, updated_at), how many are on it, the total, and next_offset (null on the last page). Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`query`	string	Up to 200 characters.
`lifecycle_stage`	string	One of: lead,trial,onboarding,customer,at_risk,churned,advocate.
`include_archived`	boolean	Default: false.
`filters`	array of objects	Conditions that must all match, e.g. [{"field": "lifecycle_stage", "op": "eq", "value": "customer"}, {"field": "renewal_date", "op": "lte", "value": "today+30"}]. field: a standard field, "tag", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N. Up to 20 items.
`filters[].field`Required	string	1 to 60 characters.
`filters[].op`Required	string	One of: contains,eq,gt,gte,in,is_empty,is_set,lt,lte,ne,starts_with.
`filters[].value`	any	Text, a number, true/false, a date, or a list for "in".
`tag`	string	Only records with this tag. Up to 60 characters.
`segment`	string	A saved segment (crm_save_segment), by name or id. Up to 80 characters.
`sort`	string	Field to sort by, "-" first for descending, e.g. "-amount" or "renewal_date". Up to 61 characters.
`limit`	integer	1 to 100. Default: 25.
`offset`	integer	At least 0. Default: 0.

The call

Over MCP, call crm_find_contacts on https://api.conecto.chat/mcp/crm. Over REST:

Terminal

curl -X POST https://api.conecto.chat/v1/tools/crm_find_contacts \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"trade","filters":[{"field":"lifecycle_stage","op":"eq","value":"customer"},{"field":"last_seen","op":"lt","value":"2026-07-01"}]}'

When it refuses

A refused call costs nothing and says what to do next.

Code	When	What to do
`invalid_input`400	A filter or the sort names a field the object does not have, uses an op that does not fit the field, or compares it with the wrong kind of value.	Check the fields with crm_list_fields and use one of the ops the message lists.
`not_found`404	No saved segment of that object has that name or id.	Call crm_list_segments; the message also names the saved segments.

More CRM tools

All 41 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md

Find contacts

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More CRM tools

Give this to your agent.