API Referencev2.0

LocalProspects API

Search for local businesses, enrich them by domain, and get back verified emails, phone carrier data, owner names, social profiles, and BBB data.

Quick Start

Get enriched business data in two API calls. Replace the API key with yours from the dashboard.

1. Find a location code

bash

curl "https://localprospects.ai/api/v1/locations?q=denver" \
  -H "x-api-key: lp_your_key"
# Returns: { locations: [{ location_code: 1012938, full_name: "Denver, Colorado, US", ... }] }

2. Search for businesses

bash

curl -X POST https://localprospects.ai/api/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_your_key" \
  -d '{"keyword": "electrician", "location_code": 1012938}'

3. Poll until enrichment completes

bash

curl https://localprospects.ai/api/v1/job/<job_id> \
  -H "x-api-key: lp_your_key"
# Poll every 5s until status === "completed"

Or enrich leads you already have

bash

curl -X POST https://localprospects.ai/api/v1/enrich \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_your_key" \
  -d '{"leads": [{"domain": "brightlineelectric.com"}]}'

Authentication

All requests require an API key via the x-api-key header. Get your key from the dashboard.

bash

curl -H "x-api-key: lp_your_key" https://localprospects.ai/api/v1/...

Claude Code

Paste this skill file into Claude Code and your agent can search and enrich leads autonomously.

local-prospects.md

# LocalProspects API

Paste this into your CLAUDE.md or project instructions.

## LocalProspects Integration

API for searching and enriching local business leads. Docs: https://localprospects.ai/docs

### Endpoints

- **Locations**: GET https://localprospects.ai/api/v1/locations?q=city+name — fuzzy search, returns location_code values
- **Search**: POST https://localprospects.ai/api/v1/search — body: { keyword, location_code } — finds businesses, returns job_id
- **Poll**: GET https://localprospects.ai/api/v1/job/:id — poll every 5s until status === "completed"
- **Results**: GET https://localprospects.ai/api/v1/job/:id/results — fetch enriched businesses once job completes
- **Enrich**: POST https://localprospects.ai/api/v1/enrich — body: { leads: [{ domain, business_name?, city?, state? }] } — enriches existing leads by domain, max 10 per request

### Auth
All endpoints require `x-api-key` header. Key stored in env var `LOCALPROSPECTS_API_KEY`.

### Credits
Two separate buckets: search credits (1 per search) and enrichment credits (1 per enriched lead). Failed enrichments are refunded automatically.

### Workflow
1. GET /v1/locations?q=miami — find location_code for your target city
2. POST /v1/search { keyword, location_code } — start search, get job_id
3. GET /v1/job/:id — poll until completed
4. GET /v1/job/:id/results — get enriched businesses

### Response Data
Each enriched business includes: owner (from BBB), email (best-match), phone + phone_type (best-match), contact (all_emails with status, all_phones with carrier), reputation (rating, reviews), web (socials, meta_description, schema_org, pages).

Look Up Locations

GET/api/v1/locations?q=:query

Fuzzy search for cities and regions. Returns location_code values required by the search endpoint. No credits consumed.

Parameters

Parameter	Type	Description
q	string	City name to search (min 2 characters). e.g. miami, denver co, austin texas

Request

bash

curl "https://localprospects.ai/api/v1/locations?q=miami" \
  -H "x-api-key: lp_your_key"

Response

Returns up to 8 matching locations, sorted by relevance (US cities first).

json

{
  "locations": [
    { "location_code": 1015116, "name": "Miami", "region": "Florida", "country": "US", "type": "City", "full_name": "Miami, Florida, US" },
    { "location_code": 1015117, "name": "Miami Beach", "region": "Florida", "country": "US", "type": "City", "full_name": "Miami Beach, Florida, US" },
    { "location_code": 9052425, "name": "Miami Gardens", "region": "Florida", "country": "US", "type": "City", "full_name": "Miami Gardens, Florida, US" },
    { "location_code": 1013446, "name": "Miami", "region": "Arizona", "country": "US", "type": "City", "full_name": "Miami, Arizona, US" }
  ]
}

Search for Businesses

POST/api/v1/search

Find businesses by niche and location. Requires a location_code from the locations endpoint. Returns a job ID — enrichment runs async in the background.

Parameters

Parameter	Type	Description
keyword	string	Business type (e.g. electrician, dentist, roofer)
location_code	integer	Location ID from GET /v1/locations (required)

Request

bash

curl -X POST https://localprospects.ai/api/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_your_key" \
  -d '{"keyword": "electrician", "location_code": 1012938}'

Response

Returns immediately with a job ID and raw business listings (not yet enriched). Use the job ID to poll for progress and fetch enriched results.

json

{
  "job_id": "a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07",
  "status": "enriching",
  "keyword": "electrician",
  "cities_searched": 1,
  "cities_missing": [],
  "total_raw": 52,
  "total_unique": 52,
  "total_enrichable": 41,
  "timings": {
    "geocode_ms": 142,
    "search_ms": 2103,
    "dedup_ms": 0,
    "total_ms": 3100
  },
  "search_details": [
    { "city": "location_1012938", "results": 274, "elapsed_ms": 10843 }
  ],
  "businesses": [
    {
      "name": "Brightline Electric",
      "phone": "+1720-555-0391",
      "website": "https://www.brightlineelectric.com/",
      "address": "4820 Elm St Suite 200, Denver, CO 80216",
      "city": "Denver",
      "state": "Colorado",
      "country_iso_code": "US",
      "rating": 4.7,
      "reviews": 178,
      "rating_distribution": { "1": 3, "2": 1, "3": 4, "4": 12, "5": 158 },
      "cid": "8827364519203847561",
      "place_id": "ChIJ_example_brightline",
      "category": "Electrician",
      "latitude": 39.7508,
      "longitude": -104.9490,
      "is_claimed": true,
      "rank_group": 1,
      "rank_absolute": 3,
      "main_image": "https://lh3.googleusercontent.com/gps-cs-s/...",
      "total_photos": 14,
      "snippet": "4820 Elm St Suite 200, Denver, CO 80216",
      "price_level": null,
      "book_online_url": null,
      "searched_city": "Denver CO"
    }
  ]
}

Poll Job Status

GET/api/v1/job/:jobId

Poll every 5 seconds until status is completed, then call the results endpoint to get enriched data.

Request

bash

curl https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07 \
  -H "x-api-key: lp_your_key"

Response (in progress)

json

{
  "job_id": "a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07",
  "status": "enriching",
  "keyword": "electrician",
  "total_businesses": 41,
  "enriched_count": 28,
  "failed_count": 5,
  "progress": 80,
  "created_at": "2026-03-15T14:22:00.000000+00:00",
  "completed_at": null
}

Response (completed)

json

{
  "job_id": "a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07",
  "status": "completed",
  "keyword": "electrician",
  "total_businesses": 41,
  "enriched_count": 36,
  "failed_count": 5,
  "progress": 100,
  "created_at": "2026-03-15T14:22:00.000000+00:00",
  "completed_at": "2026-03-15T14:23:38.000000+00:00"
}

Get Enriched Results

GET/api/v1/job/:jobId/results

Fetch the full enriched business data for a completed job. Each business includes promoted best-match email and phone, grouped sections for contact, reputation, services, and web/tech data.

Request

bash

curl https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results \
  -H "x-api-key: lp_your_key"

Response

Showing 1 business. Best email and phone are promoted to the top level. Full lists in contact.all_emails[] and contact.all_phones[].

json

{
  "businesses": [
    {
      "id": "b7e2a9f1-...",
      "name": "Brightline Electric",
      "category": "Electrician",
      "website": "https://www.brightlineelectric.com/",
      "logo": "https://www.brightlineelectric.com/logo.png",
      "rank": 3,
      "owner": "Terrence Hayes",
      "summary": null,
      "email": "info@brightlineelectric.com",
      "phone": "(720) 555-0391",
      "phone_type": "mobile",

      "contact": {
        "address": "4820 Elm St Suite 200, Denver, CO 80216",
        "city": "Denver",
        "state": "Colorado",
        "state_code": "CO",
        "country": "US",
        "lat": 39.7508,
        "lng": -104.9490,
        "all_emails": [
          {
            "email": "info@brightlineelectric.com",
            "status": "catch-all",
            "is_role_based": true,
            "is_free_provider": false
          },
          {
            "email": "terrence@brightlineelectric.com",
            "status": "verified",
            "is_role_based": false,
            "is_free_provider": false
          }
        ],
        "all_phones": [
          { "number": "(720) 555-0391", "line_type": "mobile", "carrier": "T-MOBILE USA" },
          { "number": "(303) 555-0842", "line_type": "landline", "carrier": "QWEST CORPORATION" }
        ]
      },

      "reputation": {
        "rating": 4.7,
        "reviews": 178,
        "rating_distribution": { "1": 3, "2": 1, "3": 4, "4": 12, "5": 158 },
        "is_claimed": true
      },

      "services": {
        "list": [],
        "specialties": [],
        "areas": [],
        "selling_points": [],
        "customer_types": null,
        "year_established": null,
        "employees": null
      },

      "web": {
        "tech": {
          "cms": "wordpress", "cdn": "cloudflare", "server": "nginx",
          "chat": null, "analytics": ["google_analytics"], "frameworks": ["jquery"], "other": ["schema_org", "recaptcha"]
        },
        "socials": { "facebook": "https://facebook.com/brightlineelectric", "yelp": "https://yelp.com/biz/brightline-electric-denver" },
        "has_blog": true,
        "meta_description": "Denver's trusted electrician since 2012. Panel upgrades, EV chargers, and commercial electrical...",
        "pages_crawled": 4,
        "pages": [
          { "url": "https://brightlineelectric.com/", "title": "Denver Electrician | Brightline Electric", "text": "..." }
        ]
      },

      "created_at": "2026-03-15T14:23:12.000000+00:00"
    }
  ]
}

Enrich by Domain

POST/api/v1/enrich

Already have leads? Pass an array of domains and get back the full enrichment pipeline — no search required. Each lead costs 1 enrichment credit. Failed enrichments are refunded automatically.

Parameters

Parameter	Type	Description
leads	array	Array of lead objects (max 10)
leads[].domain	string	Business domain (required)
leads[].business_name	string	Improves BBB accuracy (optional)
leads[].city	string	City name — required for BBB lookup (optional)
leads[].state	string	State code or name, e.g. CA (optional)

Request

bash

curl -X POST https://localprospects.ai/api/v1/enrich \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_your_key" \
  -d '{
    "leads": [
      { "domain": "summitridgeplumbing.com", "business_name": "Summit Ridge Plumbing", "city": "Austin", "state": "TX" },
      { "domain": "goldencrust.co" }
    ]
  }'

Response

Same structured shape as search results, minus Maps-only fields (no reputation, rank, main_image). Page text truncated below.

json

{
  "total": 1,
  "succeeded": 1,
  "failed": 0,
  "results": [
    {
      "domain": "summitridgeplumbing.com",
      "status": "success",
      "result": {
        "id": "d9c4e7a2-...",
        "name": "Summit Ridge Plumbing",
        "category": "Plumber",
        "website": "https://summitridgeplumbing.com",
        "logo": "https://summitridgeplumbing.com/images/logo.png",
        "owner": "Marco Delgado",
        "summary": null,
        "email": "marco@summitridgeplumbing.com",
        "phone": "(512) 555-0147",
        "phone_type": "mobile",

        "contact": {
          "address": "782 Riverside Dr, Austin, TX 78704",
          "city": "Austin",
          "state": "Texas",
          "state_code": "TX",
          "country": "US",
          "lat": null,
          "lng": null,
          "all_emails": [
            { "email": "marco@summitridgeplumbing.com", "status": "verified", "is_role_based": false, "is_free_provider": false }
          ],
          "all_phones": [
            { "number": "(512) 555-0147", "line_type": "mobile", "carrier": "T-MOBILE USA" }
          ]
        },

        "services": {
          "list": [],
          "specialties": [],
          "areas": [],
          "selling_points": [],
          "customer_types": null,
          "year_established": null,
          "employees": "5-10"
        },

        "web": {
          "tech": { "cms": "wordpress", "cdn": "cloudflare", "server": "nginx", "analytics": ["google_analytics"] },
          "socials": { "facebook": "https://facebook.com/summitridgeplumbing" },
          "has_blog": true,
          "pages_crawled": 3,
          "pages": [{ "url": "https://summitridgeplumbing.com/", "title": "Summit Ridge Plumbing | Austin TX", "text": "..." }]
        },

        "created_at": "2026-03-15T16:30:00.000Z"
      }
    }
  ],
  "usage": { "enrichments_charged": 1, "enrichments_refunded": 0, "enrichments_remaining": 29999 }
}

Data Fields

Every enriched business includes these fields. Null when data is unavailable.

Vitals (top-level)

Field	Description
name	Business name
category	Business category (Plumber, Dentist, etc.)
website	Website URL
logo	Logo image URL
owner	Owner name (from BBB lookup)
summary	Business summary (reserved for future use)
email	Best-match email (promoted from all_emails)
phone	Best-match phone (promoted from all_phones)
phone_type	Line type of promoted phone (mobile, landline, voip, toll_free)
rank	Search rank position (search results only)

Contact

Field	Description
contact.address	Full street address
contact.city	City
contact.state	State name
contact.state_code	State code (CA, TX, etc.)
contact.country	Country ISO code
contact.lat	Latitude
contact.lng	Longitude
contact.all_emails[]	All discovered emails
contact.all_emails[].email	Email address
contact.all_emails[].status	verified, catch-all, invalid, or unverified
contact.all_emails[].is_role_based	True for info@, admin@, support@, etc.
contact.all_emails[].is_free_provider	True for gmail.com, yahoo.com, etc.
contact.all_phones[]	All discovered phones
contact.all_phones[].number	Phone number
contact.all_phones[].line_type	landline, mobile, voip, or toll_free
contact.all_phones[].carrier	Carrier name (AT&T, Verizon, etc.)

Reputation (search results only)

Field	Description
reputation.rating	Google Maps star rating (1-5)
reputation.reviews	Total review count
reputation.rating_distribution	Breakdown by star: {1: n, 2: n, ...}
reputation.is_claimed	Whether the listing is claimed by the owner

Services (reserved)

These fields are present in the response shape but currently return empty values. They are reserved for a future release.

Field	Description
services.list	Array of services offered (currently empty)
services.specialties	Key specialties (currently empty)
services.areas	Geographic service areas (currently empty)
services.selling_points	Key differentiators (currently empty)
services.customer_types	residential, commercial, or both (currently null)
services.year_established	Year founded (currently null)
services.employees	Employee count (currently null)

Web

Field	Description
web.tech.cms	Content management system (wordpress, squarespace, etc.)
web.tech.cdn	CDN provider (cloudflare, etc.)
web.tech.server	Web server
web.tech.analytics	Analytics tools array
web.tech.frameworks	Frontend frameworks array
web.socials	Social profile URLs (facebook, instagram, etc.)
web.has_blog	Whether site has a blog
web.meta_description	Page meta description
web.pages_crawled	Number of pages analyzed
web.pages[]	Scraped pages with url, title, text

Plans

Free

10 searches · 3K enrichments

Starter

$39/mo

100 searches · 30K enrichments

Growth

$79/mo

250 searches · 75K enrichments

Pro

$129/mo

500 searches · 150K enrichments

All plans return identical data. 1 search credit per search. 1 enrichment credit per enriched lead.

Errors

Field	Description
400	Invalid request (missing params, bad domain)
401	Missing or invalid API key
429	Credit limit or rate limit exceeded
500	Internal server error

json

{ "error": "Search limit reached", "usage": 100, "limit": 100 }

Questions? Use our support chat in the bottom left.