API Reference · v1

LeadMarina API

Search local businesses by niche and city, then get them enriched — owner names, verified emails, phone line types, website insights, and socials. Base URL https://leadmarina.com.

Quick Start

Three calls: find a location, search, then poll for enriched results. Get your key on the account page.

1. Find a location code:

bash

curl "https://leadmarina.com/api/v1/locations?q=austin" \
  -H "Authorization: Bearer lm_live_xxxx"

2. Search for businesses:

bash

curl -X POST https://leadmarina.com/api/v1/search \
  -H "Authorization: Bearer lm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "plumber", "location": "Austin, TX" }'

3. Poll for the enriched results:

bash

curl https://leadmarina.com/api/v1/searches/<search_id> \
  -H "Authorization: Bearer lm_live_xxxx"
# poll every few seconds until "enrichment": "complete"

Authentication

Every request needs an API key. Send it as a bearer token (or the x-api-key header). Keep it secret — it spends your credits.

bash

Authorization: Bearer lm_live_xxxxxxxxxxxxxxxx

Look up locations

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

Fuzzy search for cities. Returns the location_code values the search endpoint accepts. No credits consumed.

json

{
  "locations": [
    { "location_code": 1026201, "name": "Austin", "full_name": "Austin, TX, Texas, United States" }
  ]
}

Search for businesses

POST/api/v1/search

Runs a live discovery search and returns the first batch of listings immediately, charging 1 credit per lead. In the background we then expand the search to find more matching leads and enrich them all — so credits_remaining here is preliminary. Poll the search (below) until enrichment is "complete" for the full results and the final balance.

query	Required. The niche/keyword, e.g. "plumber".
location	City string, e.g. "Austin, TX". (Or pass location_code.)
location_code	Optional. Exact code from /locations (skips lookup).

json

{
  "search_id": "b3e1...c4a",
  "query": "plumber",
  "location": "Austin, TX, Texas, United States",
  "delivered": 20,
  "found": 20,
  "credits_remaining": 80,
  "enrichment": "pending",
  "more_results": "pending",
  "poll": "/api/v1/searches/b3e1...c4a",
  "results": [
    { "rank": 1, "name": "Summit Ridge Plumbing", "category": "Plumber",
      "phone": "+1 512 555 0147", "rating": 4.8, "website": "https://…" }
  ]
}

Each additional lead the worker finds costs 1 credit; leads with no usable contact data are refunded automatically. The poll endpoint reports the settled credits_remaining once it's done.

Get a search (poll for enrichment)

GET/api/v1/searches/:search_id

Returns the results with enrichment filled in as the worker progresses. Poll until enrichment is "complete" — at that point every deep-fetch charge and refund has settled, so credits_remaining is final. Enriched rows add the fields below.

credits_remaining	Your live balance — final once enrichment is "complete".
delivered	Total leads in the search so far.
owner_name	The decision-maker, when found.
emails_data[]	Emails with SMTP deliverability status.
phones_data[]	Phones with line type (mobile/landline/VoIP) + carrier.
website_quality_score	1–10 site quality, plus weaknesses + services.
socials	Facebook, Instagram, LinkedIn, X, YouTube, TikTok, Yelp.
enrichment_status	pending \| enriched \| failed \| skipped (per row).

Enrich by domain

POST/api/v1/enrich

Already have leads? Pass up to 10 domains and get the full enrichment pipeline — no search required. 1 credit per lead; failed enrichments are auto-refunded. Returns a search_id to poll like a search.

leads	Required. Array of lead objects (max 10).
leads[].domain	Required. Business domain, e.g. "acme.com".
leads[].business_name	Optional. Improves accuracy.
leads[].city / .state	Optional.

bash

curl -X POST https://leadmarina.com/api/v1/enrich \
  -H "Authorization: Bearer lm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "leads": [{ "domain": "acme.com", "city": "Austin", "state": "TX" }] }'

Data fields

Every enriched business includes these (null when unavailable):

name / category	Business name and Google category.
website / gbp_url	Site URL and Google Business Profile URL.
google_cid / place_id	Google identifiers.
owner_name	Owner / decision-maker.
address / city / state	Location.
rating / reviews / claimed	Google reputation.
emails_data[]	{ email, status, is_deliverable, is_catch_all }
phones_data[]	{ phone, valid, line_type, carrier }
website_quality_score / website_weaknesses / services	Website research.
socials	Per-network profile URLs.

Errors

400	Missing/invalid params (no query, unknown location, bad domain).
401	Missing, invalid, or revoked API key.
402	Out of lead credits.
404	Search not found (or not yours).
429	Too many searches in a short window.
502	Upstream data provider error — retry.

json

{ "error": "You're out of lead credits. Top up to run another search." }

Credits

Every account starts with 100 free lead credits. Each delivered lead costs 1 credit; leads with no usable contact data are refunded. Check your balance on the account page.

← Back to LeadMarina