# Find leads with structured inputs
Search categories and locations, then run only the checks and contact steps you request. Use start-task when the job needs judgment.
**Request:** `POST https://leadsagent.io/api/v1/find`
**Access:** leads:write.
**Response:** HTTP 202. data is a task object with kind=find_leads. Poll status_url; use task-results for rows.

## Parameters

- `categories` (array of strings): Required. 1–5 business categories.
- `locations` (array of strings): Required. 1–10 cities or areas.
- `max_research_leads` (integer): Required. Research-credit cap, 1–5,000.
- `max_matching_leads` (integer): Optional. Stop when this many rows match; defaults to max_research_leads.
- `match, enrich, checks, rank_by` (object or arrays): Optional conditions, contact steps, website checks and ranking.
- `wait_seconds` (integer): Optional. Wait 0–45 seconds; default 20.
- `idempotency_key` (string): Optional. 8–128 characters. Reuse only for the same structured request.

## Request body

```json
{
  "categories": [
    "dentist"
  ],
  "locations": [
    "Austin, TX"
  ],
  "max_research_leads": 100,
  "max_matching_leads": 20,
  "enrich": {
    "emails": true
  },
  "match": {
    "has_email": true
  },
  "wait_seconds": 20,
  "idempotency_key": "austin-dentists-find-001"
}
```

## cURL

```sh
curl --fail-with-body --silent --show-error --request POST "$LEADSAGENT_API_BASE/find" -H "X-API-Key: $LEADSAGENT_API_KEY" -H "Content-Type: application/json" --data '{
  "categories": [
    "dentist"
  ],
  "locations": [
    "Austin, TX"
  ],
  "max_research_leads": 100,
  "max_matching_leads": 20,
  "enrich": {
    "emails": true
  },
  "match": {
    "has_email": true
  },
  "wait_seconds": 20,
  "idempotency_key": "austin-dentists-find-001"
}'
```

## Example response

```
{
  "request_id": "6c4d0c26-8aa3-44b0-a50a-51b832b29465",
  "status": "success",
  "data": {
    "id": "73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "kind": "find_leads",
    "status": "running",
    "prompt": "Find dentist in Austin, TX (research up to 100, keep up to 20)",
    "source": "API key · research-example",
    "max_leads": 100,
    "created_at": "2026-10-21T12:00:00+00:00",
    "updated_at": "2026-10-21T12:00:00+00:00",
    "steps": [],
    "lead_count": 0,
    "results_ready": false,
    "status_url": "/api/v1/tasks/73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4"
  },
  "meta": {}
}
```

## Notes

- Each new business researched uses one lead credit. Enrichment and checks do not use lead credits.
- A task runs for up to three search waves.

[Open the full API reference](https://leadsagent.io/documentation/api-reference)