Searches

# Start a single search

POST `/api/v1/search`

Finds decision makers at one company. Runs in the background; poll `GET /api/v1/tasks/{id}`.

## Request body

`application/json`

| Name                   | Type                           | Description                                                     |
| ---------------------- | ------------------------------ | --------------------------------------------------------------- |
| `company` Required     | string, max 255                | —                                                               |
| `titles` Required      | array of string, max 100 (1–5) | —                                                               |
| `address` Optional     | string, max 100, or null       | Where the business is. Defaults to `Global`.                    |
| `depth` Optional       | integer (1–5), or null         | Pages of search results to read (1 credit each). Defaults to 1. |
| `webhook_url` Optional | URL, max 2048, or null         | Results are POSTed here when the search finishes.               |

## Responses

- 202 Search started

- 401 The API key is missing or unknown

- 402 Not enough credits

- 403 No active Scale or Enterprise plan bought in the last 30 days

- 422 The request is not valid

- 429 More than 1,500 requests with this key in the last hour

```
curl -X POST "https://server.localcontact.ai/api/v1/search" \
  -H "Authorization: Bearer $LOCALCONTACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Acme Bakery Ltd","titles":["Owner","Founder"],"address":"London, UK"}'
```

Response · 202

```
{
  "cached": false,
  "task_id": "0f8c3a52-7f4e-4c1e-9b8a-2a5d6c1e9f00",
  "message": "Search task initiated successfully"
}
```

## Error examples

401 · The API key is missing or unknown

```
{
  "error": "API token missing"
}
```

402 · Not enough credits

```
{
  "error": "Insufficient credits",
  "required": 1,
  "available": 1
}
```

403 · No active Scale or Enterprise plan bought in the last 30 days

```
{
  "error": "API access requires an active Scale or Enterprise plan.",
  "upgrade_url": "https://localcontact.ai/dashboard/billing"
}
```

422 · The request is not valid

```
{
  "message": "string",
  "errors": {}
}
```

429 · More than 1,500 requests with this key in the last hour

```
{
  "error": "Rate limit exceeded. Max 100 requests per hour.",
  "retry_after": 3600
}
```

Source: https://localcontact.ai/docs/api/start-search · Updated: 2026-11-15
