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"}'import os
import requests
headers = {"Authorization": f"Bearer {os.environ['LOCALCONTACT_API_KEY']}"}
payload = {
"company": "Acme Bakery Ltd",
"titles": [
"Owner",
"Founder"
],
"address": "London, UK"
}
response = requests.post(
"https://server.localcontact.ai/api/v1/search",
headers=headers,
json=payload,
)
print(response.json())const headers = { Authorization: `Bearer ${process.env.LOCALCONTACT_API_KEY}` };
const response = await fetch("https://server.localcontact.ai/api/v1/search", {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({
"company": "Acme Bakery Ltd",
"titles": [
"Owner",
"Founder"
],
"address": "London, UK"
}),
});
console.log(await response.json());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
}