> ## 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.

# Search company followers

> Asynchronous. Starts a job that collects the followers of a LinkedIn company page (linkedinUrl) and returns 202 with the job; poll GET /company-followers/jobs/{jobID} or pass webhookURL, then page through GET /company-followers/jobs/{jobID}/results. limit is required, 1-50000 (larger values are rejected); a job can collect fewer followers than requested, since not every follower of a page can always be reached. countries, states, metros, jobTitles, departments and levels narrow the result and take values from the /company-followers/filters endpoints. The job creates a list named "Public API: Company Followers" in the app.

Consumes credits: your account's followers price per follower collected. The job reserves the price for the smaller of limit and the page's follower count, and at completion charges only the followers collected.

Idempotency-Key: a job with the same key in your account is returned as is, whatever the request body as long as it is valid, for as long as that job exists. A repeat does not count against the concurrent jobs limit, but it is still subject to the rate limit and can get 429; retry it with the same key.

Webhook: POST with JSON body when the job ends. A delivery that fails with a 5xx, 429 or network error is retried immediately and then redelivered in the background for up to 24h; other 4xx responses are not retried. Each attempt waits up to 8 seconds for a response. Redirects are not followed: a 3xx response is a failed delivery and is not retried. Every attempt carries the same X-Webhook-Delivery-Id header, equal to jobID, so repeated deliveries can be deduplicated. 2xx = delivered. Payload: jobID (string), status (completed|failed|no_results), linkedinUrl (string), companyName (string, omitted when unknown), followerCount (int), total (int), processed (int), error (string, present on failed and no_results). The webhook omits companyLogoUrl; fetch it from GET /company-followers/jobs/{jobID}. webhookURL must be a public http or https URL with a domain name, not an IP address, or the request fails with 400; use https.



## OpenAPI

````yaml https://api.leadsforge.ai/public/swagger/doc.json post /company-followers/search
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:
  /company-followers/search:
    post:
      tags:
        - Company followers
      summary: Search company followers
      description: >-
        Asynchronous. Starts a job that collects the followers of a LinkedIn
        company page (linkedinUrl) and returns 202 with the job; poll GET
        /company-followers/jobs/{jobID} or pass webhookURL, then page through
        GET /company-followers/jobs/{jobID}/results. limit is required, 1-50000
        (larger values are rejected); a job can collect fewer followers than
        requested, since not every follower of a page can always be reached.
        countries, states, metros, jobTitles, departments and levels narrow the
        result and take values from the /company-followers/filters endpoints.
        The job creates a list named "Public API: Company Followers" in the app.


        Consumes credits: your account's followers price per follower collected.
        The job reserves the price for the smaller of limit and the page's
        follower count, and at completion charges only the followers collected.


        Idempotency-Key: a job with the same key in your account is returned as
        is, whatever the request body as long as it is valid, for as long as
        that job exists. A repeat does not count against the concurrent jobs
        limit, but it is still subject to the rate limit and can get 429; retry
        it with the same key.


        Webhook: POST with JSON body when the job ends. A delivery that fails
        with a 5xx, 429 or network error is retried immediately and then
        redelivered in the background for up to 24h; other 4xx responses are not
        retried. Each attempt waits up to 8 seconds for a response. Redirects
        are not followed: a 3xx response is a failed delivery and is not
        retried. Every attempt carries the same X-Webhook-Delivery-Id header,
        equal to jobID, so repeated deliveries can be deduplicated. 2xx =
        delivered. Payload: jobID (string), status
        (completed|failed|no_results), linkedinUrl (string), companyName
        (string, omitted when unknown), followerCount (int), total (int),
        processed (int), error (string, present on failed and no_results). The
        webhook omits companyLogoUrl; fetch it from GET
        /company-followers/jobs/{jobID}. webhookURL must be a public http or
        https URL with a domain name, not an IP address, or the request fails
        with 400; use https.
      operationId: startCompanyFollowersSearch
      parameters:
        - description: >-
            Idempotency key - if a job with this key already exists in your
            account, the existing job is returned as is, whatever the body as
            long as it is valid. Use a new key to start a new job
          in: header
          name: Idempotency-Key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCompanyFollowersSearchRequest'
              description: Search request
              summary: body
        description: Search request
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyFollowersJobResponse'
          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, the URL is not a
            company page, the company was not found or has no followers, or a
            filter value is unknown
        '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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            conflict: a concurrent request with the same Idempotency-Key did not
            complete; retry it with the same key
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            rate_limited: too many requests, the company lookup is busy (retry
            later; Retry-After is set when known), or your account already runs
            its maximum number of concurrent jobs of this type
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'internal: unexpected server error'
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            bad_gateway: the company lookup failed temporarily; nothing is
            charged, retry later
      security:
        - ApiKeyAuth: []
components:
  schemas:
    StartCompanyFollowersSearchRequest:
      properties:
        clientRequestID:
          example: req_12345
          maxLength: 128
          type: string
        countries:
          example:
            - United States
            - Germany
          items:
            type: string
          type: array
          uniqueItems: false
        departments:
          example:
            - Engineering
            - Marketing
          items:
            type: string
          type: array
          uniqueItems: false
        jobTitles:
          example:
            - Software Engineer
            - Product Manager
          items:
            type: string
          type: array
          uniqueItems: false
        levels:
          example:
            - Senior
            - Director
          items:
            type: string
          type: array
          uniqueItems: false
        limit:
          example: 500
          maximum: 50000
          minimum: 1
          type: integer
        linkedinUrl:
          example: https://www.linkedin.com/company/salesforgeai
          type: string
        metros:
          example:
            - San Francisco Bay Area
            - Amsterdam Area
          items:
            type: string
          type: array
          uniqueItems: false
        states:
          example:
            - California
            - Bavaria
          items:
            type: string
          type: array
          uniqueItems: false
        webhookURL:
          example: https://example.com/webhooks/followers
          type: string
      required:
        - limit
        - linkedinUrl
      type: object
    CompanyFollowersJobResponse:
      properties:
        clientRequestID:
          example: req_12345
          type: string
        companyLogoUrl:
          example: https://api.leadsforge.ai/images/AbC123xYz
          type: string
        companyName:
          example: Salesforge
          type: string
        completedAt:
          type: string
        consumedCredits:
          type: number
        createdAt:
          example: '2026-03-18T12:00:00Z'
          type: string
        error:
          type: string
        followerCount:
          description: >-
            FollowerCount is the follower count of the company page when the job
            started.
          example: 12345
          type: integer
        jobID:
          example: 7c2e4a1b-9d3f-4e6a-8b5c-0f1e2d3c4b5a
          type: string
        linkedinUrl:
          example: https://www.linkedin.com/company/salesforgeai
          type: string
        processed:
          description: >-
            Processed is the number of followers collected so far. It is live on
            GET /company-followers/jobs/{jobID}; in GET /company-followers/jobs
            it stays 0 until the job ends.
          example: 120
          type: integer
        reservedCredits:
          type: number
        resultsURL:
          example: >-
            /public/v1/company-followers/jobs/7c2e4a1b-9d3f-4e6a-8b5c-0f1e2d3c4b5a/results
          type: string
        status:
          enum:
            - in_progress
            - completed
            - failed
            - no_results
          example: in_progress
          type: string
        statusURL:
          example: >-
            /public/v1/company-followers/jobs/7c2e4a1b-9d3f-4e6a-8b5c-0f1e2d3c4b5a
          type: string
        total:
          description: >-
            Total is the number of followers the job aims to collect: the
            smaller of limit and followerCount.
          example: 500
          type: integer
        updatedAt:
          example: '2026-03-18T12:01:00Z'
          type: string
        webhookURL:
          example: https://example.com/webhooks/followers
          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
  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.