API
Get a search (poll for enrichment)
Poll a search as verification completes and page through its enriched rows, with the settled balance.
API
Poll a search as verification completes and page through its enriched rows, with the settled balance.
API
Poll a search as verification completes and page through its enriched rows, with the settled balance.
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 the background run has ended and every charge has settled, so credits_remaining is final. Enriched rows add the fields below.
Results come in pages. Each call returns one page of the search's leads in rank order — limit leads (default 50, max 1,000) starting at offset, both query parameters. delivered counts the whole search; next_offset is where the next page starts, and null on the last one. To read every lead, keep calling with ?offset= set to next_offset until it comes back null.
curl "https://leadmarina.com/api/v1/searches/<search_id>?limit=1000&offset=1000" \
-H "Authorization: Bearer lm_live_xxxx"
# → "delivered": 2400, "showing": { "offset": 1000, "limit": 1000, "returned": 1000 }, "next_offset": 2000Where a search is. enrichment stays "pending" for the whole background run, so read stage to know what is happening:
| queued | Waiting for a worker slot. Accounts run in parallel, one search each at a time; your own searches run in the order created. queue_position is your place in your own queue. |
| discovering | Finding businesses and expanding across cities. |
| enriching | Checking each business's website. progress counts finished rows; results fill in as they complete. |
| verifying | Every row is delivered. Emails and phones are being verified on a shared verification queue — often the longest phase, and not a stall: results are already readable. |
| complete | Done; every charge has settled. |
| cancelled | Cancelled before enrichment with DELETE; un-enriched rows were removed and refunded. |
Typical durations: a 300-lead search takes 5–15 minutes when the queue is quiet and 20–40 minutes under load, occasionally longer, most of it in verifying. A search reaches enrichment: "complete" when its background run has ended for any reason; read stage to tell complete from failed or cancelled. The same progress for more than 15 minutes in enriching is worth reporting; a long verifying is not.
DELETE/api/v1/searches/:search_id
Cancels a search that is still queued: its un-enriched rows are removed and refunded, and the account slot is released. A search that is already running is left to finish; the response is 409 with the current stage. If the search or its status cannot be read just then, the response is a 500 that says nothing was changed — try again.
When a read fails on our side, GET answers with a 500 that says so — never with an empty or finished search. Poll again shortly.
| stage | queued | discovering | enriching | verifying | complete | failed | cancelled. |
| stage_note | One sentence explaining the stage. |
| queue_position | For queued searches: your place in your own account's queue (1 = next). null otherwise, or when the queue could not be counted just then. |
| started_at | When a worker picked the search up; null while queued. |
| progress | { done, total } rows enriched so far. |
| credits_remaining | Leads you can spend right now — final once enrichment is "complete". On a plan with no monthly quota this is what is left in the current 7-day period, and credits_window reports { limit, used, resets_at }. |
| delivered | Total leads in the search so far — the whole search, not this page. |
| showing | This page: { offset, limit, returned }, where limit is the page size that applied. |
| next_offset | Pass as ?offset= for the next page; null on the last page. |
| owner_name | Likely owner/decision-maker when we can identify one — best-effort, only a fraction of leads. |
| contact_name / contact_title | The person the business's own website names as running part of it — a general manager, an office manager, the practice's doctor — when it names no owner, and their role as the site gives it. null otherwise. |
| people[] | Everyone the business's own website names as working there: { name, title, kind }, kind one of owner, manager, practitioner, staff. null when it names no one. |
| emails_data[] | Emails we found (up to 3 per lead), each with an SMTP deliverability status. |
| phones_data[] | Phones we found (up to 3 per lead), each with line_type — usually mobile | fixed_line (landline) | voip | toll_free, sometimes unknown or fixed_line_or_mobile — plus carrier and valid; null where a number could not be looked up. |
| socials | Facebook, Instagram, LinkedIn, X, YouTube, TikTok, Yelp. |
| enrichment_status | pending | enriched | failed | skipped. |
| enrichment_error | What went wrong, when something did. On a failed lead: why the website check failed — e.g. "site unreachable", "DNS resolution failed", "blocked by an interstitial". An enriched lead can still carry one (e.g. "owner extraction unavailable: …") — the site was crawled and the contacts are good, only that step did not run. null when nothing went wrong. |
| services, service_areas, years_in_business, trust_signals, website_quality_score, website_weaknesses, outreach_hook | DEPRECATED — always empty since June 2026, removed on 2026-10-15. Do not build on them; for website state use website_status. |
| website_status | none | live | unreachable | blocked | unknown | pending — one word for the state of the lead's website, derived from website + enrichment_status + enrichment_error. |
| emails_data[].status | safe | risky | invalid | unknown (checked, could not be confirmed). |
| data_sources | Present when some of these leads' emails or owner names may come from open datasets and public records: the page with their sources, licences and notices (also sent as a Link header, rel="license"). Pass it on with any of this data you share. |
Line type and carrier are checked against telephone numbering and portability data at verification time. How you contact leads is up to you — see our Terms for data-accuracy and outreach-responsibility details (e.g. TCPA rules for calling or texting wireless numbers).