[Cotlet](https://cotlet.dev/index.md) · [Integrations](https://cotlet.dev/integrations.md) · [How it works](https://cotlet.dev/how-it-works.md) · [Use cases](https://cotlet.dev/use-cases.md) · [Security](https://cotlet.dev/security.md) · [For developers](https://cotlet.dev/for-developers.md) · [For automation agencies](https://cotlet.dev/for-agencies.md) · [Blog](https://cotlet.dev/blog.md) · [API docs](https://cotlet.dev/docs.md) · [Help center](https://cotlet.dev/help.md) · [Changelog](https://cotlet.dev/changelog.md) · [Contact](https://cotlet.dev/contact.md) · [Pricing](https://cotlet.dev/pricing.md) · [Sign up](https://cotlet.dev/signup)

# Start lead search

> Start an Intellimatch search for companies that match a description, with contacts if you ask for them. Inputs, cURL, Python and Node.js examples and an example response.

Source: https://cotlet.dev/docs/api/findymail/start_lead_search

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

Start an Intellimatch search for companies that match a description, with contacts if you ask for them.

Findymail API: https://cotlet.dev/docs/api/findymail.md

`POST https://cotlet.dev/api/v1/findymail/lead-search/start`

Access: write. Confirm: waits for the user's OK before it runs.

Returns a hash. Pass it to get_lead_search to follow the search and read the rows. The search spends Findymail credits: 1 per 10 companies in broad mode or 1 per company in targeted mode, plus 1 per contact, 1 per email and 10 per phone found, charged when the export is generated. By default you confirm each call; you can switch that off for this tool.

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Plain-English description of your target companies. |
| `limit` | integer | no | Companies to find, 100 by default, 5000 at most. |
| `mode` | string | no | broad (default, includes adjacent companies) or targeted (fewer, more precise). |
| `target_job_titles` | array | no | Up to 3 tiers of job titles in priority order, for example [["Head of Growth", "VP Marketing"]]. Default [["CEO"]]. |
| `find_contact` | boolean | no | Find a contact at each company. |
| `find_email` | boolean | no | Find the contact email. |
| `find_phone` | boolean | no | Find the contact phone number. |
| `require_email` | boolean | no | Keep only companies where an email was found. Needs find_contact and find_email. |
| `exclusion_list_ids` | array | no | Exclusion list IDs to apply. 0 is the global list (default), -1 applies none. |

## Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/findymail/lead-search/start \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Agencies in Europe specializing in paid ads for e-commerce","limit":200,"mode":"targeted","target_job_titles":[["Head of Growth","VP Marketing"]],"find_contact":true,"find_email":true,"exclusion_list_ids":[1204]}'
```

**Python**

```python
result = client.call("findymail", "start_lead_search", {"query":"Agencies in Europe specializing in paid ads for e-commerce","limit":200,"mode":"targeted","target_job_titles":[["Head of Growth","VP Marketing"]],"find_contact":True,"find_email":True,"exclusion_list_ids":[1204]})
```

**Node.js**

```js
const result = await cotlet.call('findymail', 'start_lead_search', {"query":"Agencies in Europe specializing in paid ads for e-commerce","limit":200,"mode":"targeted","target_job_titles":[["Head of Growth","VP Marketing"]],"find_contact":true,"find_email":true,"exclusion_list_ids":[1204]});
```

**CLI**

```bash
cotlet call findymail start_lead_search --data '{"query":"Agencies in Europe specializing in paid ads for e-commerce","limit":200,"mode":"targeted","target_job_titles":[["Head of Growth","VP Marketing"]],"find_contact":true,"find_email":true,"exclusion_list_ids":[1204]}'
```

## Example response

```json
{
  "hash": "f3b9a1c27d5e4086"
}
```

Previous: [Delete exclusion list](https://cotlet.dev/docs/api/findymail/delete_exclusion_list.md)

---

Give your AI agents your signed-in browser.

**Product:** [Integrations](https://cotlet.dev/integrations.md) · [Use cases](https://cotlet.dev/use-cases.md) · [How it works](https://cotlet.dev/how-it-works.md) · [Pricing](https://cotlet.dev/pricing.md) · [Security](https://cotlet.dev/security.md)

**Resources:** [Blog](https://cotlet.dev/blog.md) · [API docs](https://cotlet.dev/docs.md) · [Help center](https://cotlet.dev/help.md) · [Changelog](https://cotlet.dev/changelog.md) · [GitHub](https://github.com/cotletdev/cotlet)

**Solutions:** [For developers](https://cotlet.dev/for-developers.md) · [For automation agencies](https://cotlet.dev/for-agencies.md)

**Company:** [About](https://cotlet.dev/about.md) · [AI info: company facts](https://cotlet.dev/ai-info.md) · [Contact](https://cotlet.dev/contact.md)

**Legal:** [Terms of service](https://cotlet.dev/terms) · [Privacy policy](https://cotlet.dev/privacy) · [Refund policy](https://cotlet.dev/refunds) · [Acceptable use](https://cotlet.dev/acceptable-use) · [Cookie policy](https://cotlet.dev/cookies) · [DPA](https://cotlet.dev/dpa) · [Subprocessors](https://cotlet.dev/subprocessors)

**Elsewhere:** [Status page](https://status.cotlet.dev) · [Cotlet on GitHub](https://github.com/cotletdev) · [Cotlet on X](https://x.com/cotletdev) · [Cotlet on LinkedIn](https://www.linkedin.com/company/cotletdev) · [Cotlet on Product Hunt](https://www.producthunt.com/products/cotlet) · [Cotlet on Crunchbase](https://www.crunchbase.com/organization/cotlet) · [Cotlet on SaaSHub](https://www.saashub.com/cotlet)

Cotlet.dev is built by Bart Krawczyk and Jake Slugocki, the founders of Take Group sp. z o.o., ul. Wincentego Janasa 4, 40-855 Katowice, Poland. KRS 0000871398, NIP 6342984273, VAT EU: PL6342984273. [About us](https://cotlet.dev/about.md)

Cotlet is an independent service. It is not affiliated with, endorsed by or sponsored by any of the products listed on this site. Product names are trademarks of their respective owners.