> ## Documentation Index
> Fetch the complete documentation index at: https://developer.salesforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich owners of local businesses

> Asynchronous. Starts an owner search for up to 200 businesses of one search job (searchJobID, businessIDs), looking for up to maxResults owners per business and the requested contact channels (wantEmail and/or wantPhone), and returns 202 with the job; poll GET /maps-discovery/owner-jobs/{jobID} or pass webhookURL, then page through GET /maps-discovery/owner-jobs/{jobID}/results.

Consumes credits: your account's maps owner email and phone prices per contact found. The job holds credits only for businesses that need a new owner search: maxResults x the price of each requested channel, per business, and settles per contact found; a business with no owner costs nothing. Owners already found recently for the same place in your account, by this search or an earlier one, are reused without a new owner search and hold nothing, but their missing email/phone is still looked up and charged at the same prices, so consumedCredits can exceed reservedCredits.

Only one owner job per search runs at a time; a second one while the first is in progress is refused with 409. Each business in the businesses list gets a status: queued; cached (owners already found are reused); skipped (not part of this search job, or could not be processed; see reason); already_enriching (its ID appears more than once in the request). If none is accepted the job ends as no_results.

Supports the Idempotency-Key header and webhookURL as POST /maps-discovery/search 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 and no_results jobs, and on completed jobs that stopped looking up contacts early because credits ran out).



## OpenAPI

````yaml https://api.leadsforge.ai/public/swagger/doc.json post /maps-discovery/enrich-owners
openapi: 3.1.0
info:
  description: >-
    Search B2B leads, find their work emails, phone numbers and LinkedIn
    profiles, and discover lookalike companies, company page followers and local
    businesses.


    Authenticate every request with your API key in the `Authorization` header:
    the raw key, no `Bearer` prefix. Create the key in the Leadsforge app under
    Settings -> API & MCP.


    Paid operations consume credits from your account balance, and each
    operation says whether it is paid. Long-running operations are asynchronous:
    they return a job that you poll (or receive by webhook) and then page
    through its results.


    Errors return a JSON body with a human-readable `message` and, except for an
    unknown path (404), a stable `code`. Program against `code`. A JSON body
    with a field the operation does not accept is rejected with 400 bad_request,
    listing the unknown fields in data.validations. A request still running when
    the server timeout is reached is cut off with 503 and an empty body.
  license:
    name: Proprietary
    url: https://www.leadsforge.ai/terms
  termsOfService: https://www.leadsforge.ai/terms
  title: Leadsforge API
  version: '1.0'
servers:
  - url: https://api.leadsforge.ai/public/v1
security: []
tags:
  - description: Your account's credit balance.
    name: Balance
  - description: >-
      Find people by role, seniority, company, location and other filters.
      Searches and counts are free up to a monthly allowance, then each one
      costs credits; finding contact details is charged separately.
    name: Search
  - description: >-
      Accepted values for the controlled filters of POST /search and POST
      /search/count, and a resolver for location strings. All free.
    name: Search filters
  - description: >-
      Find work emails, phone numbers and LinkedIn profiles. Asynchronous jobs
      take up to 500 people; synchronous calls take one person and answer in the
      same response.
    name: Enrichment
  - description: >-
      Find companies similar to the domains you give. Previews are free up to a
      monthly allowance, then each one costs credits; the search consumes
      credits per company returned.
    name: Lookalikes
  - description: >-
      Find the people who follow a LinkedIn company page. Asynchronous jobs that
      consume credits per follower collected.
    name: Company followers
  - description: >-
      Find local businesses in an area you choose, then find their owners'
      emails and phone numbers. Both steps are asynchronous jobs that consume
      credits.
    name: Maps discovery
  - description: Scrape LinkedIn Sales Navigator searches.
    name: salesnav
externalDocs:
  description: Leadsforge API guides
  url: >-
    https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment
paths:
  /maps-discovery/enrich-owners:
    post:
      tags:
        - Maps discovery
      summary: Enrich owners of local businesses
      description: >-
        Asynchronous. Starts an owner search for up to 200 businesses of one
        search job (searchJobID, businessIDs), looking for up to maxResults
        owners per business and the requested contact channels (wantEmail and/or
        wantPhone), and returns 202 with the job; poll GET
        /maps-discovery/owner-jobs/{jobID} or pass webhookURL, then page through
        GET /maps-discovery/owner-jobs/{jobID}/results.


        Consumes credits: your account's maps owner email and phone prices per
        contact found. The job holds credits only for businesses that need a new
        owner search: maxResults x the price of each requested channel, per
        business, and settles per contact found; a business with no owner costs
        nothing. Owners already found recently for the same place in your
        account, by this search or an earlier one, are reused without a new
        owner search and hold nothing, but their missing email/phone is still
        looked up and charged at the same prices, so consumedCredits can exceed
        reservedCredits.


        Only one owner job per search runs at a time; a second one while the
        first is in progress is refused with 409. Each business in the
        businesses list gets a status: queued; cached (owners already found are
        reused); skipped (not part of this search job, or could not be
        processed; see reason); already_enriching (its ID appears more than once
        in the request). If none is accepted the job ends as no_results.


        Supports the Idempotency-Key header and webhookURL as POST
        /maps-discovery/search 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 and no_results jobs, and on completed jobs
        that stopped looking up contacts early because credits ran out).
      operationId: startMapsOwnerEnrichment
      parameters:
        - description: >-
            Idempotency key - if a job with this key already exists in your
            account, the existing job is returned as is
          in: header
          name: Idempotency-Key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichMapsOwnersRequest'
              description: Owner enrichment request
              summary: body
        description: Owner enrichment request
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapsOwnerJobResponse'
          description: Job created
          headers:
            Location:
              description: Path of the new job, same as statusURL
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'bad_request: the body or a parameter is invalid'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            missing_api_key, invalid_api_key, or unauthorized when your account
            is blocked
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            insufficient_credits: the balance does not cover the credits this
            request reserves
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            account_frozen: credit spending is paused for your account; contact
            support
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'not_found: search job not found'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            conflict: owner enrichment is already in progress for this search
            (including one started in the app), or the search has not started
            yet
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            rate_limited: too many requests, retry later; Retry-After is set
            when known
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'internal: unexpected server error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EnrichMapsOwnersRequest:
      properties:
        businessIDs:
          example:
            - 3c1a2b4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
          items:
            format: uuid
            type: string
          maxItems: 200
          minItems: 1
          type: array
          uniqueItems: false
        clientRequestID:
          example: req_12345
          maxLength: 128
          type: string
        maxResults:
          description: MaxResults is the number of owners to look for per business.
          example: 3
          maximum: 8
          minimum: 1
          type: integer
        searchJobID:
          example: 5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60
          type: string
        wantEmail:
          description: >-
            WantEmail asks for owner emails. Set at least one of wantEmail and
            wantPhone, or the request fails with 400.
          example: true
          type: boolean
        wantPhone:
          description: >-
            WantPhone asks for owner phone numbers. Set at least one of
            wantEmail and wantPhone, or the request fails with 400.
          example: true
          type: boolean
        webhookURL:
          example: https://example.com/webhooks/maps-owners
          type: string
      required:
        - businessIDs
        - maxResults
        - searchJobID
      type: object
    MapsOwnerJobResponse:
      properties:
        accepted:
          description: >-
            Accepted is the number of businesses that got an owner search:
            queued plus cached.
          example: 48
          type: integer
        businesses:
          items:
            $ref: '#/components/schemas/MapsOwnerBusinessItem'
          type: array
          uniqueItems: false
        clientRequestID:
          example: req_12345
          type: string
        completedAt:
          type: string
        consumedCredits:
          type: number
        createdAt:
          example: '2026-09-13T12:10:00Z'
          type: string
        error:
          description: >-
            Error is set on failed and no_results jobs, and on completed jobs
            that stopped looking up contacts early because

            credits ran out.
          type: string
        jobID:
          example: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
          type: string
        maxResults:
          example: 3
          type: integer
        ownersFound:
          example: 0
          type: integer
        processed:
          description: >-
            Processed is the number of accepted businesses whose owner search
            has finished; it never exceeds accepted. It is live on GET
            /maps-discovery/owner-jobs/{jobID}; in GET
            /maps-discovery/owner-jobs it stays 0 until the job ends. Use
            status, not processed, to tell when the job is done.
          example: 12
          type: integer
        reservedCredits:
          type: number
        resultsURL:
          example: >-
            /public/v1/maps-discovery/owner-jobs/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/results
          type: string
        searchJobID:
          example: 5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60
          type: string
        status:
          enum:
            - in_progress
            - completed
            - failed
            - no_results
          example: in_progress
          type: string
        statusURL:
          example: >-
            /public/v1/maps-discovery/owner-jobs/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
          type: string
        total:
          description: >-
            Total is the number of business IDs in the request, duplicates
            included.
          example: 50
          type: integer
        updatedAt:
          example: '2026-09-13T12:11:00Z'
          type: string
        wantEmail:
          example: true
          type: boolean
        wantPhone:
          example: true
          type: boolean
        webhookURL:
          example: https://example.com/webhooks/maps-owners
          type: string
      type: object
    ApiError:
      properties:
        code:
          description: >-
            Code is the stable, machine-readable error code; each endpoint lists
            the codes it returns.
          type: string
        data:
          description: >-
            Data carries details for some errors; on validation errors it is
            {"validations": ["..."]}, one message per

            invalid field.
        message:
          type: string
      type: object
    MapsOwnerBusinessItem:
      properties:
        businessID:
          example: 3c1a2b4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
          type: string
        reason:
          example: business not found in this list
          type: string
        status:
          enum:
            - queued
            - cached
            - skipped
            - already_enriching
          example: skipped
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Your API key, sent as is (no `Bearer` prefix). Create it in the
        Leadsforge app under Settings -> API & MCP.
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.