Bulk uploads
Start a bulk search from a CSV file
POST /api/v1/bulk/upload
Rows without a company (or without a location, when a location column is used) are skipped, and duplicate company + location rows count once. Columns are detected from the header when not given: company = first header containing "company" (else the first column); location = first containing "location", "address" or "city". Comma, semicolon, tab and pipe delimiters are detected.
Request body
multipart/form-data
| Name | Type | Description |
|---|---|---|
file Required | file | CSV or TXT, at most 20 MB |
titles Required | array of string, max 100 (1–5) | — |
depth Required | integer (1–8) | — |
company_column Optional | string, max 100 | — |
location_column Optional | string, max 100 | — |
file_name Optional | string, max 255 | Shown in the task list (default: the uploaded file name) |
webhook_url Optional | URL, max 2048 | — |
skip_previous Optional | boolean | Leave out companies anyone searched in the last 30 days. |
Responses
-
202 Bulk search queued
-
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/bulk/upload" \
-H "Authorization: Bearer $LOCALCONTACT_API_KEY" \
-F "[email protected]" \
-F "titles[]=Owner" \
-F "titles[]=Founder" \
-F "depth=1"import os
import requests
headers = {"Authorization": f"Bearer {os.environ['LOCALCONTACT_API_KEY']}"}
with open("businesses.csv", "rb") as f:
response = requests.post(
"https://server.localcontact.ai/api/v1/bulk/upload",
headers=headers,
files={"file": f},
data={"titles[]": ["Owner", "Founder"], "depth": 1},
)
print(response.json())const headers = { Authorization: `Bearer ${process.env.LOCALCONTACT_API_KEY}` };
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("businesses.csv")]), "businesses.csv");
form.append("titles[]", "Owner");
form.append("titles[]", "Founder");
form.append("depth", "1");
const response = await fetch("https://server.localcontact.ai/api/v1/bulk/upload", { method: "POST", headers, body: form });
console.log(await response.json());Response · 202
{
"task_id": "0f8c3a52-7f4e-4c1e-9b8a-2a5d6c1e9f00",
"total_companies": 1,
"skipped_no_company": 1,
"skipped_no_location": 1,
"skipped_previous": 1,
"status": "pending",
"message": "Bulk search job queued 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
}