Skip to main content
Local businesses such as dental clinics, restaurants or agencies are rarely well covered by B2B databases. Maps discovery finds them in an area you choose, and owner enrichment finds the people who run them, with their emails and phone numbers.
  • 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.
All examples send your API key in the 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 (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.
The response is 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 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).
The response is 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.