CRM

Find companies

crm_find_companies · Reads only · Markdown

Finds companies by name or domain, 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.

Which hotels and restaurants already buy from us?

Your agent callscrm_find_companiesFree*

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

{
  "lifecycle_stage": "customer",
  "tag": "hospitality"
}

What comes back

{
  "companies": [
    {
      "id": 4103,
      "name": "Café Lotte",
      "domain": "",
      "website": "",
      "industry": "Food and drink",
      "employee_count": null,
      "lifecycle_stage": "customer",
      "notes": "",
      "tags": [
        "hospitality"
      ],
      "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 organisations is needed: all hotel customers, prospects in one industry.

For one quick lookup from a name or domain, use crm_search.

What it does

Search companies by name or domain, or by filters on any field, tag or custom field, or by a saved segment. Archived companies are left out unless include_archived is true. Returns a page, the total, and next_offset for the next page.

What comes back

A page of companies with their fields, tags and custom fields, how many are on it, the total and next_offset. Archived companies are left out unless include_archived is true; with it, the filter archived_at is_set lists only them. 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: prospect,onboarding,customer,churned.
`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_companies on https://api.conecto.chat/mcp/crm. Over REST:

Terminal

curl -X POST https://api.conecto.chat/v1/tools/crm_find_companies \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lifecycle_stage":"customer","tag":"hospitality"}'

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 companies

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.