Skip to content

Soon Coming soon: work and personal email enrichment. Join the early list

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.

Errors

Errors come back as JSON with an error message. What each status means:

Error status codes
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

Book a demo

Loading…