API docs · v1.0
LocalContact API
Send a business name and address. Get the people who run it.
Quick start
- Create an API key. API access comes with the Scale plan. Create a key in the app under API.
- Start a search.
POST /api/v1/searchwith a business name, an address and up to 5 job titles. You get atask_idback straight away. - Read the people. Poll
GET /api/v1/tasks/{id}untilstatusiscompleted, then readGET /api/v1/tasks/{id}/results. Or pass awebhook_urland we'll post the results to you.
# 1. Start a search (1 credit)
curl -X POST https://server.localcontact.ai/api/v1/search \
-H "Authorization: Bearer $LOCALCONTACT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"company": "Bramblewood Bakery", "address": "Austin, TX", "titles": ["Owner", "Founder"]}'
# 2. When GET /api/v1/tasks/{task_id} says "completed", read the people
curl https://server.localcontact.ai/api/v1/tasks/$TASK_ID/results \
-H "Authorization: Bearer $LOCALCONTACT_API_KEY"import os, time
import requests
API = "https://server.localcontact.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['LOCALCONTACT_API_KEY']}"}
task = requests.post(f"{API}/search", headers=headers, json={
"company": "Bramblewood Bakery",
"address": "Austin, TX",
"titles": ["Owner", "Founder"],
}).json()
while True:
status = requests.get(f"{API}/tasks/{task['task_id']}", headers=headers).json()["status"]
if status in ("completed", "failed"):
break
time.sleep(2)
people = requests.get(f"{API}/tasks/{task['task_id']}/results", headers=headers).json()["data"]const API = "https://server.localcontact.ai/api/v1";
const headers = {
Authorization: `Bearer ${process.env.LOCALCONTACT_API_KEY}`,
"Content-Type": "application/json",
};
const { task_id } = await fetch(`${API}/search`, {
method: "POST",
headers,
body: JSON.stringify({ company: "Bramblewood Bakery", address: "Austin, TX", titles: ["Owner", "Founder"] }),
}).then((r) => r.json());
let status = "pending";
while (!["completed", "failed"].includes(status)) {
await new Promise((r) => setTimeout(r, 2000));
({ status } = await fetch(`${API}/tasks/${task_id}`, { headers }).then((r) => r.json()));
}
const { data: people } = await fetch(`${API}/tasks/${task_id}/results`, { headers }).then((r) => r.json());GET /api/v1/tasks/{id}/results
{
"data": [
{
"name": "Maria Lopez",
"title": "Owner",
"company_name": "Bramblewood Bakery",
"company_domain": "bramblewood.example",
"company_type": "Bakery",
"company_address": "Austin, US"
},
{
"name": "Daniel Lopez",
"title": "Co-owner",
"company_name": "Bramblewood Bakery",
"company_domain": "bramblewood.example",
"company_type": "Bakery",
"company_address": "Austin, US"
}
],
"meta": { "total": 2, "page": 1, "per_page": 20, "last_page": 1 }
}Base URL
https://server.localcontact.ai
Authentication
Send your API key as a bearer token: Authorization: Bearer YOUR_KEY. The
api_token header with the same key also works. If you send both,
api_token wins. Keep keys on your server, never in browser code.
Access
The API needs a Scale (or Enterprise) purchase in the last 30 days whose credits haven't
expired. Without one, every endpoint answers 403.
Credits
A search costs 1 credit for each page of search results it reads (depth, 1 by
default). Every person found is included. A bulk upload needs enough credits for every
business in the file and charges for each one it searches.
Rate limits
1,500 requests per key per hour. Over that, you get 429 with
retry_after in seconds.
Stability
/api/v1 is frozen: the same URLs, headers and JSON fields. Changes only ever add
things, such as new optional fields or endpoints. See the changelog.
Errors
Errors come back as JSON with an error message. What each status means:
| Name | Type | Description |
|---|---|---|
400 Optional | status | The request can't be done yet. |
401 Optional | status | The API key is missing or wrong. |
402 Optional | status | Not enough credits. |
403 Optional | status | Your plan doesn't include the API. |
404 Optional | status | Not found, or it isn't yours. |
422 Optional | status | Something in the request isn't valid, or results aren't ready. |
429 Optional | status | Too many requests. Wait and try again. |
Endpoints
- POST
/api/v1/searchStart a single search - GET
/api/v1/tasksList your searches (single and bulk), newest first - GET
/api/v1/tasks/{id}Status of a search - GET
/api/v1/tasks/{id}/resultsPeople found by a completed search - POST
/api/v1/bulk/uploadStart a bulk search from a CSV file - GET
/api/v1/bulk/tasksAll your bulk tasks, newest first (not paginated) - GET
/api/v1/bulk/tasks/{taskId}One bulk task - GET
/api/v1/bulk/tasks/{taskId}/resultsPeople found by a bulk task - GET
/api/v1/bulk/tasks/{taskId}/downloadResults of a completed bulk task as CSV