> ## 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 (preview)

> Count the followers of a company page and price their extraction

Find out how many people follow a company's LinkedIn page, and what extracting
them would cost, before spending any credits. This is the free first step of
the two-step competitor-followers signal:

1. **Preview** (this endpoint) returns the company, its follower count and the
   price. No credits.
2. **[Extract](https://docs.pipecorn.com/api-reference/endpoints/signals/competitor_followers.md)** starts
   an async extraction of the followers into a search. Spends enrichment
   credits.

## Credits and requirements

* Credits: **free**
* Requires a connected LinkedIn account: the follower count comes from LinkedIn.
  Without one the request returns `422`.
* Authentication: standard v2 scheme (`X-API-KEY`)

## The company URL

`company_linkedin_url` is the company's LinkedIn page:
`https://www.linkedin.com/company/<name>`, or `/school/` and `/showcase/` pages.
A numeric `https://www.linkedin.com/company/<id>` URL works too when your LinkedIn
account has Sales Navigator, which turns the id into the page's name. A page
LinkedIn does not know returns `404`.

## Accepted keys

The body takes `company_linkedin_url`. The extract-only keys `limit`,
`persona`, `webhook_url` and `name` are accepted and ignored, so the same body
works for the preview and the
[extract](https://docs.pipecorn.com/api-reference/endpoints/signals/competitor_followers.md) call. Any
other key is rejected with `422`.

## Example request

```json theme={null}
{
  "company_linkedin_url": "https://www.linkedin.com/company/pipecorn"
}
```

## Example response

```json theme={null}
{
  "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,
  "credits_per_follower": 1,
  "minimum_credits": 1000,
  "estimated_credits": 4210
}
```

`estimated_credits` is the price of extracting every follower:
`max(follower_count, minimum_credits)`.


## OpenAPI

````yaml POST /intents/leads/competitor_followers/preview
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/preview:
    post:
      summary: Preview competitor followers
      description: >-
        Look up a company's LinkedIn page and return its follower count and the
        price of extracting its followers. Free: spends no credits. Requires a
        connected LinkedIn account. The extract-only keys (`limit`, `persona`,
        `webhook_url`, `name`) are accepted and ignored, so one body works for
        both the preview and `POST /intents/leads/competitor_followers`. Unknown
        keys return 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - company_linkedin_url
              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: Accepted and ignored.
                persona:
                  type: string
                  format: uuid
                  description: Accepted and ignored.
                webhook_url:
                  type: string
                  format: uri
                  description: Accepted and ignored.
                name:
                  type: string
                  description: Accepted and ignored.
      responses:
        '200':
          description: The company and the price of extracting its followers
          content:
            application/json:
              schema:
                type: object
                required:
                  - company
                  - follower_count
                  - credits_per_follower
                  - minimum_credits
                  - estimated_credits
                properties:
                  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
                    description: People following the company page on LinkedIn.
                    example: 4210
                  credits_per_follower:
                    type: integer
                    description: Enrichment credits charged per extracted follower.
                    example: 1
                  minimum_credits:
                    type: integer
                    description: >-
                      Minimum charge per extraction, whatever the number of
                      followers.
                    example: 1000
                  estimated_credits:
                    type: integer
                    description: >-
                      Credits to extract every follower: `max(follower_count,
                      minimum_credits)`.
                    example: 4210
              example:
                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
                credits_per_follower: 1
                minimum_credits: 1000
                estimated_credits: 4210
        '400':
          description: '`company_linkedin_url` is missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: company_linkedin_url is required
        '401':
          description: Unauthorized (missing or invalid API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: LinkedIn has no company page at this URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Company not found on LinkedIn
        '422':
          description: >-
            Unprocessable entity: `company_linkedin_url` is not a LinkedIn
            company page URL, or the body has keys the endpoint does not accept
            (listed in `unauthorized_params`, next to every accepted key in
            `permitted_params`), or no usable LinkedIn connection on the
            account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_url:
                  summary: Not a company page URL
                  value:
                    error: >-
                      company_linkedin_url must be a LinkedIn company page URL
                      (e.g. https://www.linkedin.com/company/pipecorn)
                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:
  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.
  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.