API docs · v1.0

# LocalContact API

Send a business name and address. Get the people who run it.

## Quick start

1. **Create an API key.** API access comes with the Scale plan. Create a key in the app under API.
2. **Start a search.** `POST /api/v1/search` with a business name, an address and up to 5 job titles. You get a `task_id` back straight away.
3. **Read the people.** Poll `GET /api/v1/tasks/{id}` until `status` is `completed`, then read `GET /api/v1/tasks/{id}/results`. Or pass a `webhook_url` and 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"
```

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](https://localcontact.ai/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/search` Start a single search](https://localcontact.ai/docs/api/start-search)
- [GET `/api/v1/tasks` List your searches (single and bulk), newest first](https://localcontact.ai/docs/api/list-tasks)
- [GET `/api/v1/tasks/{id}` Status of a search](https://localcontact.ai/docs/api/get-task)
- [GET `/api/v1/tasks/{id}/results` People found by a completed search](https://localcontact.ai/docs/api/get-task-results)
- [POST `/api/v1/bulk/upload` Start a bulk search from a CSV file](https://localcontact.ai/docs/api/upload-bulk)
- [GET `/api/v1/bulk/tasks` All your bulk tasks, newest first (not paginated)](https://localcontact.ai/docs/api/list-bulk-tasks)
- [GET `/api/v1/bulk/tasks/{taskId}` One bulk task](https://localcontact.ai/docs/api/get-bulk-task)
- [GET `/api/v1/bulk/tasks/{taskId}/results` People found by a bulk task](https://localcontact.ai/docs/api/get-bulk-results)
- [GET `/api/v1/bulk/tasks/{taskId}/download` Results of a completed bulk task as CSV](https://localcontact.ai/docs/api/download-bulk-results)

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