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 "file=@businesses.csv" \
  -F "titles[]=Owner" \
  -F "titles[]=Founder" \
  -F "depth=1"
```

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
}
```

Source: https://localcontact.ai/docs/api/upload-bulk · Updated: 2026-11-15
