API Referencev2.0

Local Prospects API

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

Quick Start

For searches across multiple areas, use a campaign. The direct search example below is for a one-off or deliberately small single-location search. 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, "depth": 300}'

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

Loading skill…

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)
depth	integer	Maximum provider results: 100, 300, 500, or 700 (optional; default 300)

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, "depth": 300}'

Response

The selected depth is reserved before provider work begins. The response reports the final charge and refund; a failed search refunds the full reservation. Use the job ID to poll for enrichment progress and fetch 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,
  "credits_reserved": 300,
  "leads_charged": 52,
  "credits_refunded": 248,
  "leads_remaining": 948,
  "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",
      "google_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"
    }
  ]
}

Insufficient credits

The request returns 429 before provider work begins when the account cannot reserve the selected depth.

json

{
  "error": "Not enough lead credits -- 300 required to search",
  "code": "insufficient_credits",
  "required_credits": 300,
  "available_credits": 100
}

Search Campaigns

POST/api/v1/campaigns

Create a resumable multi-location search. Campaigns are available on every plan and use the same lead-credit balance as ordinary searches. Only the next location must fit the current balance; a low balance pauses the campaign and it must be resumed manually after credits are added.

Create a campaign

Parameter	Type	Description
keyword	string	One business niche for this campaign
campaign_id	UUID	Optional client-generated idempotency key; safely reuse it when retrying create
name	string	Optional display name
max_leads	integer	Optional campaign-wide stopping limit
scope.include	integer[]	Ordered country, region, or city location codes
scope.exclude	integer[]	Descendants to omit from an included area
scope.default_depth	integer	100, 300, 500, or 700; campaigns default to 100
scope.depth_overrides	object	Optional location-code to depth overrides

bash

curl -X POST https://localprospects.ai/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_your_key" \
  -d '{
    "name": "California plumbers",
    "keyword": "plumber",
    "max_leads": 5000,
    "scope": {
      "include": [21137],
      "exclude": [1014369],
      "default_depth": 100,
      "depth_overrides": { "1014221": 700 }
    }
  }'

Use POST /api/v1/campaigns/preview with the same body to resolve and review the plan without saving it.

Lifecycle and results

Field	Description
GET /api/v1/campaigns	List campaigns for the API key owner
GET /api/v1/campaigns/:id	Campaign, ordered plan, child searches, stats, and activity
PATCH /api/v1/campaigns/:id	Edit a draft or paused plan; the active location is locked
POST /api/v1/campaigns/:id/actions/start	Start a ready campaign
POST /api/v1/campaigns/:id/actions/pause	Prevent another location from starting
POST /api/v1/campaigns/:id/actions/resume	Continue a paused or attention-needed campaign
POST /api/v1/campaigns/:id/actions/stop	Permanently stop future searches
GET /api/v1/campaigns/:id/leads	Paginated, cross-search deduplicated campaign leads
GET /api/v1/campaigns/:id/plan	Paginate large frozen execution plans
GET /api/v1/campaigns/:id/export	Download the deduplicated campaign pool as CSV
POST /api/v1/campaigns/:id/searches	Attach an existing same-keyword search with { job_id }
GET /api/v1/campaign-locations	Browse countries, regions, and cities for scope codes

Each child is a normal search job with a campaign_id. Searches run one at a time, reserve their selected depth, charge only returned leads, and refund the unused reservation. A no-results response completes with zero leads, while a real failed location is recorded in the final campaign totals. The campaign lead view and export merge repeated businesses; V1 billing is still settled independently for each child search.

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, GBP phone, mobile number when found, 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"

Optional filters

Add any of these boolean query parameters to narrow the returned businesses. Use true to require the data or false to require it to be absent. Omitted filters do not change results, and combined filters use AND logic. Filters apply to JSON and every CSV format.

Parameter	Type	Description
has_website	boolean	Business has a website URL
has_email	boolean	Business has at least one discovered email
has_phone	boolean	Business has at least one phone of any known type
has_mobile_phone	boolean	Business has at least one phone classified as mobile

bash

# Businesses with both an email and any phone
curl "https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results?has_email=true&has_phone=true" \
  -H "x-api-key: lp_your_key"

# Businesses without a website that have a mobile phone
curl "https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results?has_website=false&has_mobile_phone=true" \
  -H "x-api-key: lp_your_key"

Response formats

The endpoint returns the existing JSON structure by default. Add the optional format query parameter to download a CSV using the same export presets available in the dashboard. Choosing a representation does not rerun the search or consume additional credits.

Field	Description
json	Default. Returns { businesses: [...] } using the full structured API response
simple	Compact outreach CSV with core business, contact, and reputation columns
advanced	Full enrichment CSV with primary fields plus discovered emails, phones, and website pages
ghl	GoHighLevel-ready contact CSV with owner, business, contact, source, and category fields
instantly	Instantly-ready lead CSV with predefined contact and personalization fields; businesses without an email are omitted
1cw	1ClickWebsite Lead Gen CSV with business name, phone, email, address, color, and logo

CSV examples

bash

# Advanced CSV
curl "https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results?format=advanced" \
  -H "x-api-key: lp_your_key" \
  -o leads-advanced.csv

# GoHighLevel CSV
curl "https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results?format=ghl" \
  -H "x-api-key: lp_your_key" \
  -o leads-ghl.csv

# Instantly CSV
curl "https://localprospects.ai/api/v1/job/a3f8c21d-7b04-4e19-9c6a-d42e8f1b5a07/results?format=instantly" \
  -H "x-api-key: lp_your_key" \
  -o leads-instantly.csv

CSV responses use text/csv and include attachment, result-format, and result-count headers. Unsupported format or filter values return 400 with the valid options.

JSON response

Showing 1 business. Best email, GBP phone, and mobile number 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",
      "mobile_number": "(720) 555-0391",

      "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",
            "is_role_based": true,
            "is_free_provider": false
          },
          {
            "email": "terrence@brightlineelectric.com",
            "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

Parameter	Type	Description
leads	array	Array of lead objects (max 10)
leads[].domain	string	Business domain (required)
leads[].business_name	string	Improves enrichment accuracy (optional)
leads[].city	string	City name (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",
        "mobile_number": "(512) 555-0147",

        "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", "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. The same format values and optional result filters are supported for testing integrations.

bash

curl https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine/results
curl "https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine/results?has_mobile_phone=true"
curl "https://localprospects.ai/api/v1/demo/job/demo-job-plumbers-irvine/results?has_email=true&format=ghl" -o demo-ghl.csv

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)

Field	Description
name	Business name
category	Business category (Plumber, Dentist, etc.)
website	Website URL
gbp_url	Google Business Profile URL
google_cid	Google Maps CID
place_id	Google Place ID
logo	Logo image URL
owner	Owner name
summary	Business summary (reserved for future use)
email	Best-match email (promoted from all_emails)
phone	GBP phone when available, otherwise best available discovered phone
phone_type	Line type of phone (mobile, landline, voip, toll_free)
mobile_number	First mobile phone found; may duplicate phone when the GBP phone is mobile
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[].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

100 leads

Starter

$39/mo

10,000 leads/mo, or $29/mo billed yearly

Agency

$97/mo

50,000 leads/mo, or $79/mo billed yearly

Scale

$297/mo

200,000 leads/mo, or $229/mo billed yearly

All plans return identical data. Lead credits reset monthly, including yearly subscriptions.

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.