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

# Competitor followers

> Extract the people who follow a company page on LinkedIn

Extract the people who follow a company's LinkedIn page, typically a
competitor's, into a lead list. Run the
[preview](https://docs.pipecorn.com/api-reference/endpoints/signals/competitor_followers_preview.md) first
to see the follower count and the price for free.

This signal is part of the **Growth plan**. Below it, the request is refused
with `403` and
`{"error": "This signal is part of the Growth plan. Upgrade to save these leads to a list."}`.

## Credits

* **1 enrichment credit per follower**, with a minimum of **1,000 credits** per
  extraction. A `limit` of 300 still costs 1,000 credits.
* `limit` is capped to the company's follower count, and you are charged for
  that capped count.
* The credits are reserved when the request is accepted. When fewer followers
  come back than reserved, the difference is refunded.
* Without enough credits the request returns `402` with
  `code: "insufficient_credits"` and a `top_up_url`, and no extraction starts.
  See [Credit and limit errors](https://docs.pipecorn.com/api-reference/errors.md).

The endpoint is exempt from request rate limiting: the credit balance is its
own throttle. It requires a connected LinkedIn account.

## Body

* `company_linkedin_url` **(required)**: the company's LinkedIn page, with its
  name (`https://www.linkedin.com/company/<name>`) or numeric id (with Sales Navigator)
* `limit` **(required)**: how many followers to extract
* `persona`: a persona UUID, to keep only the followers who match its Sales
  Navigator search
* `webhook_url`: where the leads are POSTed when the extraction finishes
* `name`: the name of the lead list, up to 75 characters. Defaults to
  `Followers of <company>`.

Any other key is rejected with `422`.

## Getting the results

The extraction runs outside LinkedIn and takes from several minutes to a few
hours, depending on the number of followers. The response returns a
`search_id` right away:

* Poll `status_url`, which is
  [`GET /searches/{id}`](https://docs.pipecorn.com/api-reference/endpoints/searches/show), until
  `status` is `finished`. It then returns the leads, paginated.
* With `webhook_url`, the leads are also POSTed there once the extraction
  finishes, in the same payload as other searches.

The list also appears in the app, under **My lists**, once the **API / MCP** toggle is on.

## Example request

```json theme={null}
{
  "company_linkedin_url": "https://www.linkedin.com/company/pipecorn",
  "limit": 2000,
  "webhook_url": "https://your-company.com/webhooks/competitor-followers"
}
```

## Example response

```json theme={null}
{
  "message": "Competitor followers extraction started. Results land on the search once the scrape finishes.",
  "search_id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc",
  "company": {
    "name": "Pipecorn",
    "linkedin_id": "12345678",
    "linkedin_url": "https://www.linkedin.com/company/pipecorn",
    "industry": "Software Development",
    "employee_range": "11-50",
    "location": "Paris, Île-de-France"
  },
  "follower_count": 4210,
  "expected_profiles_count": 2000,
  "credits_reserved": 2000,
  "status_url": "https://app.pipecorn.com/api/v2/searches/8e1dcba0-f0bb-4071-99fc-f18ba6559ccc"
}
```


## OpenAPI

````yaml POST /intents/leads/competitor_followers
openapi: 3.0.1
info:
  title: Pipecorn Signals API
  description: Pipecorn Accounts API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /intents/leads/competitor_followers:
    post:
      summary: Extract competitor followers
      description: >-
        Start an asynchronous extraction of the people who follow a company's
        LinkedIn page. Costs 1 enrichment credit per follower with a minimum of
        1,000 credits per extraction; the credits are reserved when the request
        is accepted and the unused part is refunded when fewer followers come
        back. Part of the Growth plan. Requires a connected LinkedIn account.
        Poll `status_url` (`GET /searches/{id}`) until `status` is `finished`;
        with `webhook_url` the leads are also posted there. Unknown keys return
        422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - company_linkedin_url
                - limit
              properties:
                company_linkedin_url:
                  type: string
                  format: uri
                  description: >-
                    LinkedIn company page URL of the competitor:
                    `/company/<name>`, `/school/<name>` or `/showcase/<name>`. A
                    numeric `/company/<id>` URL works when the LinkedIn account
                    has Sales Navigator.
                  example: https://www.linkedin.com/company/pipecorn
                limit:
                  type: integer
                  minimum: 1
                  description: >-
                    Number of followers to extract. Capped to the company's
                    follower count. Any value below 1,000 is still charged 1,000
                    credits.
                  example: 2000
                persona:
                  type: string
                  format: uuid
                  description: >-
                    Persona UUID: keep only the followers who match its Sales
                    Navigator search.
                  example: 550e8400-e29b-41d4-a716-446655440000
                webhook_url:
                  type: string
                  format: uri
                  description: >-
                    URL that receives the leads when the extraction finishes, in
                    the same payload as other searches.
                  example: https://your-company.com/webhooks/competitor-followers
                name:
                  type: string
                  maxLength: 75
                  description: Name of the lead list. Defaults to `Followers of <company>`.
                  example: Followers of Pipecorn - Q4
      responses:
        '201':
          description: Extraction started
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - search_id
                  - company
                  - follower_count
                  - expected_profiles_count
                  - credits_reserved
                  - status_url
                properties:
                  message:
                    type: string
                    example: >-
                      Competitor followers extraction started. Results land on
                      the search once the scrape finishes.
                  search_id:
                    type: string
                    format: uuid
                    description: ID of the search the followers land on.
                    example: 8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
                  company:
                    type: object
                    description: >-
                      The company LinkedIn returned. Fields LinkedIn leaves
                      blank are omitted.
                    properties:
                      name:
                        type: string
                        example: Pipecorn
                      linkedin_id:
                        type: string
                        example: '12345678'
                      linkedin_url:
                        type: string
                        format: uri
                        example: https://www.linkedin.com/company/pipecorn
                      industry:
                        type: string
                        example: Software Development
                      employee_range:
                        type: string
                        example: 11-50
                      location:
                        type: string
                        example: Paris, Île-de-France
                  follower_count:
                    type: integer
                    example: 4210
                  expected_profiles_count:
                    type: integer
                    description: >-
                      Followers that will be extracted: `limit`, capped to
                      `follower_count`.
                    example: 2000
                  credits_reserved:
                    type: integer
                    description: >-
                      Credits reserved for this extraction:
                      `max(expected_profiles_count, 1000)`.
                    example: 2000
                  status_url:
                    type: string
                    format: uri
                    description: >-
                      Where to poll the extraction: `GET /searches/{id}`. Same
                      value as the `Location` header.
                    example: >-
                      https://app.pipecorn.com/api/v2/searches/8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
              example:
                message: >-
                  Competitor followers extraction started. Results land on the
                  search once the scrape finishes.
                search_id: 8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
                company:
                  name: Pipecorn
                  linkedin_id: '12345678'
                  linkedin_url: https://www.linkedin.com/company/pipecorn
                  industry: Software Development
                  employee_range: 11-50
                  location: Paris, Île-de-France
                follower_count: 4210
                expected_profiles_count: 2000
                credits_reserved: 2000
                status_url: >-
                  https://app.pipecorn.com/api/v2/searches/8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
          headers:
            Location:
              description: Status URL of this extraction, `GET /searches/{id}`.
              schema:
                type: string
                format: uri
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '400':
          description: '`company_linkedin_url` or `limit` is missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: limit is required
        '401':
          description: Unauthorized (missing or invalid API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            Not enough enrichment credits for the extraction. No extraction
            starts and nothing is spent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
              example:
                error: >-
                  Not enough enrichment credits. You need 2000 credits but only
                  have 350 available.
                code: insufficient_credits
                top_up_url: https://app.pipecorn.com/settings/subscriptions/credits
        '403':
          description: >-
            Competitor followers is part of the Growth plan; accounts below it
            are refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  This signal is part of the Growth plan. Upgrade to save these
                  leads to a list.
        '404':
          description: >-
            LinkedIn has no company page at this URL, or `persona` is not a
            persona of the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                company:
                  summary: Unknown company
                  value:
                    error: Company not found on LinkedIn
                persona:
                  summary: Unknown persona
                  value:
                    error: Persona not found
        '422':
          description: >-
            Unprocessable entity: invalid `company_linkedin_url`, `limit` or
            `webhook_url`, a company with no followers, or keys the endpoint
            does not accept, or no usable LinkedIn connection on the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_followers:
                  summary: Company without followers
                  value:
                    error: This company has no followers to extract
                invalid_limit:
                  summary: limit is not a positive integer
                  value:
                    error: Limit must be greater than 0
                unknown_parameter:
                  summary: Unknown key in the body
                  value:
                    error: Unauthorized parameters detected
                    unauthorized_params:
                      - company
                    permitted_params:
                      - company_linkedin_url
                      - limit
                      - persona
                      - webhook_url
                      - name
                linkedin_not_connected:
                  summary: No usable LinkedIn connection
                  value:
                    error: >-
                      LinkedIn credentials not found. Please connect your
                      LinkedIn account.
        '429':
          description: >-
            LinkedIn rate limited the connected account during the company
            lookup. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The LinkedIn company lookup failed. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: LinkedIn request failed. Please retry later.
components:
  headers:
    Idempotent-Replayed:
      description: >-
        `true` when this response is a replay of an earlier request sent with
        the same `Idempotency-Key`. Nothing was run or charged again.
      schema:
        type: string
        enum:
          - 'true'
  schemas:
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: >-
            Human-readable error message. A few validation errors return a list
            of messages instead of a single string.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        message:
          type: string
          description: >-
            Longer explanation, sent by validators that add context. Such errors
            may also carry extra top-level keys like `valid_values` or
            `example`.
        details:
          type: string
          description: >-
            Parser message, sent with `"Invalid JSON format in request body"`
            when the request body is not valid JSON.
        unauthorized_params:
          type: array
          items:
            type: string
          description: >-
            The request keys the endpoint does not accept, sent with
            `"Unauthorized parameters detected"`.
        permitted_params:
          type: array
          items:
            type: string
          description: >-
            Sent with `"Unauthorized parameters detected"`. The stack endpoints
            list every key they accept; hiring and growth list the accepted keys
            present in the request.
    InsufficientCreditsError:
      required:
        - error
        - code
        - top_up_url
      type: object
      properties:
        error:
          type: string
          description: >-
            Human-readable message. Endpoints priced per result report the
            shortfall instead, e.g. "Not enough enrichment credits. You need 30
            credits but only have 5 available."
          example: Not enough enrichment credits left
        code:
          type: string
          enum:
            - insufficient_credits
          description: Machine-readable error code
        top_up_url:
          type: string
          format: uri
          description: >-
            Absolute URL of the credits page. Buy credits there, then replay the
            request.
          example: https://app.pipecorn.com/settings/subscriptions/credits
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````

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