- Service: Leadsforge API
- Base URL:
https://api.leadsforge.ai/public/v1 - Cost: your maps discovery price for each business found, then your maps owner email and phone prices for each contact found. See Credits.
Authorization header and read it from $LEADSFORGE_API_KEY.
1
Choose categories
GET /maps-discovery/filters/categories lists recommended category values. Only businesses whose primary category contains one of your categories as a whole word are kept. Matching ignores case but needs the whole word, so use the category’s own wording, usually singular: dentist or Dentist matches, dentists does not.2
Start a search
Give a center point, a radius in kilometres (up to 500), 1 to 100 categories and how many places to scan (The response is
limit, 1 to 5000). language is optional. Pass a webhookURL to get one notification when the job ends; it is tried up to 3 times and not redelivered later.202 Accepted with the job; keep its jobID to poll the search, read its results and find owners. It reserves your maps discovery price for limit businesses and charges only for the businesses found. limit caps the places scanned before the category filter, so the number found can be well below it.3
Wait for the search
Poll
GET /maps-discovery/jobs/{jobID} until the status is completed, failed or no_results.4
Read the businesses
Results fill in as the search finishes, so read them once the status is final. Page through them, up to 200 per page.
5
Find the owners
Send the search’s The response is
jobID as searchJobID, up to 200 businessID values from it, the channels you want (at least one of wantEmail and wantPhone) and how many owners to look for per business (maxResults, 1 to 8).202 Accepted with the owner job, including its jobID, and in businesses a status for each business: queued (a new owner search starts), cached (owners found recently are reused), skipped (see reason) or already_enriching (its ID appears more than once in the request). Only one owner enrichment job per search runs at a time; a request while one is still running, including one started in the app, gets 409 conflict.6
Read the owners
Poll
GET /maps-discovery/owner-jobs/{jobID} until it is final, then page through GET /maps-discovery/owner-jobs/{jobID}/results. Each owner carries the businessID it belongs to, a name, a title, and the email and phone found.Owners found recently for the same place in your account, by this search or an earlier one, are reused without a new owner search. Their missing email or phone is still looked up at your maps owner prices, free when your account obtained that value in the last 30 days.
