maps-discovery

Enrich owners of local businesses

Starts an async owner search for up to 200 businesses of one search job, looking for up to maxResults owners per business and the requested contact channels (email and/or phone). Credits are reserved for the upper bound (maps owner email/phone price x maxResults per business) and settled per contact found; a business with no owner costs nothing, and businesses enriched recently are served from cache at no cost. Owner contacts the maps providers miss are backfilled by the standard email/phone waterfall at the same price; consumedCredits on the job includes that backfill. Only one owner job per search runs at a time - a second one while the first is in progress is refused with 409. Businesses not found or not owned by the account are reported as skipped in the businesses list without failing the call. Supports the Idempotency-Key header and webhookURL as the search endpoint does. Webhook payload: jobID (string), status (completed|failed|no_results), searchJobID (string), total (int), processed (int), ownersFound (int), consumedCredits (number), error (string; present on failed jobs, and on completed jobs whose email/phone backfill stopped early for insufficient credits).

post/maps-discovery/enrich-owners

Request

  • Base URL: https://api.leadsforge.ai
  • URL: https://api.leadsforge.ai/maps-discovery/enrich-owners
  • Auth: ApiKeyAuth (a scheme the document does not define)

Headers

Idempotency-Keystring

Idempotency key - if a job with this key already exists for this account, the existing job is returned as-is

Request body

businessIDsstring[] required
clientRequestIDstring
maxResultsinteger required

MaxResults is the number of owners to look for per business.

searchJobIDstring required
wantEmailboolean
wantPhoneboolean
webhookURLstring

Example request

{
  "businessIDs": [
    "3c1a2b4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "clientRequestID": "req_12345",
  "maxResults": 3,
  "searchJobID": "5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60",
  "wantEmail": true,
  "wantPhone": true,
  "webhookURL": "https://example.com/webhooks/maps-owners"
}

Response

Job created

acceptedinteger
clientRequestIDstring
completedAtstring
consumedCreditsnumber
createdAtstring
errorstring

set on failed jobs, and on completed jobs whose email/phone backfill stopped early for insufficient credits

jobIDstring
maxResultsinteger
ownersFoundinteger
processedinteger
reservedCreditsnumber
resultsURLstring
searchJobIDstring
status'in_progress' | 'completed' | 'failed' | 'no_results'
statusURLstring
totalinteger
updatedAtstring
wantEmailboolean
wantPhoneboolean
webhookURLstring

Example response

{
  "accepted": 48,
  "businesses": [
    {
      "businessID": "3c1a2b4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "reason": "business not found or not owned by account",
      "status": "queued"
    }
  ],
  "clientRequestID": "req_12345",
  "completedAt": "2026-09-13T12:25:00Z",
  "createdAt": "2026-09-13T12:10:00Z",
  "jobID": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "maxResults": 3,
  "processed": 12,
  "reservedCredits": 2880,
  "resultsURL": "/public/v1/maps-discovery/owner-jobs/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/results",
  "searchJobID": "5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60",
  "status": "in_progress",
  "statusURL": "/public/v1/maps-discovery/owner-jobs/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "total": 50,
  "updatedAt": "2026-09-13T12:11:00Z",
  "wantEmail": true,
  "wantPhone": true,
  "webhookURL": "https://example.com/webhooks/maps-owners"
}

Changes

No recorded changes to this operation across all 1 revision of this API.