API
Get a search (poll for enrichment)
Poll a search as verification completes; enriched rows and 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 every lead has been charged and verified, so credits_remaining is final. Enriched rows add the fields below.
Where 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 | Crawling 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.
| 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. |
| 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. |
| owner_name | Likely owner/decision-maker when we can identify one — best-effort, only a fraction of leads. |
| 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 — mobile | fixed_line (landline) | voip | toll_free — plus carrier and valid. |
| socials | Facebook, Instagram, LinkedIn, X, YouTube, TikTok, Yelp. |
| enrichment_status | pending | enriched | failed | skipped. |
| emails_data[].status | safe | risky | invalid | unknown (checked, could not be confirmed). |
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).