Local Prospects
API Referencev2.0

Local Prospects API

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

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/...

Agent Skill

Paste this skill file into Claude Code, Codex, Manus, or any other agent platform to search and enrich leads autonomously.

local-prospects.md
# LocalProspects API

Paste this into your CLAUDE.md, Codex instructions, Manus instructions, or other agent project instructions.

## LocalProspects Integration

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

### Auth
All endpoints require x-api-key header. Ask the user for their API key before making requests. The key starts with lp_.

### 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
- Demo: use /api/v1/demo/* versions to test with fake data. Demo endpoints do not need auth and do not use credits.

### Credits
Single pool: lead credits. Each business found via search or enriched via /v1/enrich costs 1 lead credit. Failed enrichments are refunded automatically. Searches require 100+ leads to initiate.

### 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
5. Export all results to CSV using this exact header order:

```csv
Google Maps Rank,Name,Category,Website,Owner,Email,Phone,Phone Type,Address,City,State,Rating,Reviews,Review Snippet,Claimed,Socials,Logo URL,Main Image URL,Email 1,Email 1 Status,Email 2,Email 2 Status,Email 3,Email 3 Status,Email 4,Email 4 Status,Email 5,Email 5 Status,Phone 1,Phone 1 Type,Phone 1 Carrier,Phone 2,Phone 2 Type,Phone 2 Carrier,Phone 3,Phone 3 Type,Phone 3 Carrier,Phone 4,Phone 4 Type,Phone 4 Carrier,Phone 5,Phone 5 Type,Phone 5 Carrier,Page 1 URL,Page 1 Title,Page 1 Meta,Page 1 Text,Page 2 URL,Page 2 Title,Page 2 Meta,Page 2 Text,Page 3 URL,Page 3 Title,Page 3 Meta,Page 3 Text,Page 4 URL,Page 4 Title,Page 4 Meta,Page 4 Text,Page 5 URL,Page 5 Title,Page 5 Meta,Page 5 Text
```

Use the best-match primary fields for Owner, Email, Phone, and Phone Type. Put all discovered emails and phones into the numbered columns with their verification status, line type, and carrier. Put crawled website pages into Page 1-5 URL, Title, Meta, and Text columns.

### Response Data
Each enriched business includes: owner name, 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

ParameterTypeDescription
qstringCity 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

ParameterTypeDescription
keywordstringBusiness type (e.g. electrician, dentist, roofer)
location_codeintegerLocation 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 lead credit. Failed enrichments are refunded automatically.

Parameters

ParameterTypeDescription
leadsarrayArray of lead objects (max 10)
leads[].domainstringBusiness domain (required)
leads[].business_namestringImproves enrichment accuracy (optional)
leads[].citystringCity name (optional)
leads[].statestringState 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": { "leads_charged": 1, "leads_refunded": 0, "leads_remaining": 4999 }
}

Demo Endpoints

Use these endpoints to test integrations with fake local-business data. They do not require an API key, do not call the search or enrichment workers, and never consume credits.

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

Returns sample location codes for client-side location lookup flows.

bash
curl "https://localprospects.ai/api/v1/demo/locations?q=irvine"
POST/api/v1/demo/search

Returns a fake search response with job_id, raw business listings, timings, and enrichable counts.

bash
curl -X POST https://localprospects.ai/api/v1/demo/search \
  -H "Content-Type: application/json" \
  -d '{"keyword": "plumber", "location_code": 1013883}'
GET/api/v1/demo/job/:jobId

Returns a fake job status. Add ?status=enriching to test polling UI while a job is still running.

bash
curl https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine
curl "https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine?status=enriching"
GET/api/v1/demo/job/:jobId/results

Returns fake enriched search results in the same transformed shape as the production results endpoint.

bash
curl https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine/results
POST/api/v1/demo/enrich

Returns fake enrichment data for supplied domains. /api/v1/demo/enhance is available as an alias.

bash
curl -X POST https://localprospects.ai/api/v1/demo/enrich \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "domain": "harborpipe.example", "business_name": "Harbor Pipe & Drain", "city": "Irvine", "state": "CA" }
    ]
  }'

Example Response Marker

Every demo response includes demo: true, so SDKs and test suites can assert they are using fixture data.

json
{
  "job_id": "demo-job-plumbers-irvine",
  "status": "enriching",
  "keyword": "plumber",
  "location_code": 1013883,
  "total_unique": 2,
  "total_enrichable": 2,
  "demo": true
}

Data Fields

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

Vitals (top-level)

FieldDescription
nameBusiness name
categoryBusiness category (Plumber, Dentist, etc.)
websiteWebsite URL
logoLogo image URL
ownerOwner name
summaryBusiness summary (reserved for future use)
emailBest-match email (promoted from all_emails)
phoneBest-match phone (promoted from all_phones)
phone_typeLine type of promoted phone (mobile, landline, voip, toll_free)
rankSearch rank position (search results only)

Contact

FieldDescription
contact.addressFull street address
contact.cityCity
contact.stateState name
contact.state_codeState code (CA, TX, etc.)
contact.countryCountry ISO code
contact.latLatitude
contact.lngLongitude
contact.all_emails[]All discovered emails
contact.all_emails[].emailEmail address
contact.all_emails[].statusverified, catch-all, invalid, or unverified
contact.all_emails[].is_role_basedTrue for info@, admin@, support@, etc.
contact.all_emails[].is_free_providerTrue for gmail.com, yahoo.com, etc.
contact.all_phones[]All discovered phones
contact.all_phones[].numberPhone number
contact.all_phones[].line_typelandline, mobile, voip, or toll_free
contact.all_phones[].carrierCarrier name (AT&T, Verizon, etc.)

Reputation (search results only)

FieldDescription
reputation.ratingGoogle Maps star rating (1-5)
reputation.reviewsTotal review count
reputation.rating_distributionBreakdown by star: {1: n, 2: n, ...}
reputation.is_claimedWhether 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.

FieldDescription
services.listArray of services offered (currently empty)
services.specialtiesKey specialties (currently empty)
services.areasGeographic service areas (currently empty)
services.selling_pointsKey differentiators (currently empty)
services.customer_typesresidential, commercial, or both (currently null)
services.year_establishedYear founded (currently null)
services.employeesEmployee count (currently null)

Web

FieldDescription
web.tech.cmsContent management system (wordpress, squarespace, etc.)
web.tech.cdnCDN provider (cloudflare, etc.)
web.tech.serverWeb server
web.tech.analyticsAnalytics tools array
web.tech.frameworksFrontend frameworks array
web.socialsSocial profile URLs (facebook, instagram, etc.)
web.has_blogWhether site has a blog
web.meta_descriptionPage meta description
web.pages_crawledNumber of pages analyzed
web.pages[]Scraped pages with url, title, text

Plans

Free

$0

250 leads

Starter

$29/mo

10,000 leads/mo

Pro

$97/mo

50,000 leads/mo

Agency

$197/mo

200,000 leads/mo

All plans return identical data. 1 lead credit per business found or enriched.

Errors

FieldDescription
400Invalid request (missing params, bad domain)
401Missing or invalid API key
429Credit limit or rate limit exceeded
500Internal server error
json
{ "error": "Search limit reached", "usage": 100, "limit": 100 }

Questions? Use our support chat in the bottom left.