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

# Find companies growing

> Start a LinkedIn account (company) search by growth criteria. Only documented fields are allowed; unknown keys return 422.

**Valid criteria (choose one mode):**
1. **Company-wide headcount growth:** Provide at least one of `min_headcount_growth_percentage` or `max_headcount_growth_percentage`. Do not send `department` in this mode.
2. **Department metrics:** Send `department` (LinkedIn function ID as a string, e.g. `"1"`) plus at least one of `min_department_headcount`, `max_department_headcount`, `min_department_headcount_growth_percentage`, or `max_department_headcount_growth_percentage`.

Department fields cannot be combined with company-wide headcount growth fields.

Find companies that are experiencing growth using company-wide headcount growth or department-level metrics. The search runs against LinkedIn account data; matching companies are imported and sent to your webhook.

Send parameters inside a top-level JSON object under the key `account`. Only documented fields are allowed; extra keys under `account` are rejected with a validation error.

## Growth criteria (pick one approach)

**1. Company-wide headcount growth**

Provide at least one of:

* `min_headcount_growth_percentage`
* `max_headcount_growth_percentage`

Do not send `department` in this mode. Company-wide headcount growth and department filters cannot be used together.

**2. Department-level metrics**

Always send `department` (a string ID for the LinkedIn function to target, for example `"1"`). Also include at least one of:

* `min_department_headcount` and/or `max_department_headcount`, or
* `min_department_headcount_growth_percentage` and/or `max_department_headcount_growth_percentage`

`department` alone is not enough. Department headcount or department growth fields without `department` are not allowed.

### Other fields (inside `account`)

* `webhook_url` (**required**): URL that receives results when processing completes.
* `streaming` (optional): Whether to stream results as they are processed.
* `limit` (optional): Maximum number of companies to import. If omitted, the import is still capped at **1000** companies even when the search finds more; the `total` field in the response reflects the full match count from the search when no limit is set.

### Filters

* `company_size`: Array of company size range strings (LinkedIn-style buckets). En-dash characters in values are normalized to hyphens on the server.
* `included_locations`: Array of location IDs to include.
* `excluded_locations`: Array of location IDs to exclude.
* `included_industries`: Array of industry IDs to include.

Allowed `company_size` values:

* `1-10`
* `11-50`
* `51-200`
* `201-500`
* `501-1000`
* `1001-5000`
* `5001-10000`
* `10001+`

For the complete list of industry IDs, see the [LinkedIn Industry List](https://docs.google.com/spreadsheets/d/1qTFPVfcSHnL5PU1AcQlzD8mCmfSICKJ4WuU-OBGhkdI/edit?gid=0#gid=0).

Common industry IDs include:

* `4` - Automotive
* `6` - Technology, Information and Internet
* `12` - Education
* `43` - Financial Services
* `96` - Software Development

### Department validation

`department` must be a string and must be one of the allowed LinkedIn function IDs used by the API.

## Response

Successful requests return **201 Created** with:

* `message`: Confirmation that the account search started and results will be sent to the webhook.
* `id`: UUID of the import job.
* `total`: If `limit` is set, this is the smaller of the search size and `limit`. If `limit` is omitted, this is the full search size (import volume may still be capped at 1000 as above).
* `preview`: Up to **10** sample companies, each with `company_name`, `industry`, `linkedin_id` (numeric ID from the result), and `linkedin_url` in the form `https://www.linkedin.com/company/{linkedin_id}`.

In development environments, responses may also include `account_url` for debugging.

## Example request

```json theme={null}
{
    "webhook_url": "https://your-company.com/webhooks/growth",
    "min_headcount_growth_percentage": 10,
    "company_size": ["51-200"],
    "included_locations": [103644278],
    "streaming": false
}
```

## Example response

```json theme={null}
{
  "message": "Account search started successfully. You will receive the results on your webhook shortly.",
  "id": "5d4fabd2-e26d-47d1-b0de-4bf370f7b799",
  "total": 150,
  "preview": [
    {
      "company_name": "Acme Inc",
      "industry": "Software Development",
      "linkedin_id": "123456",
      "linkedin_url": "https://www.linkedin.com/company/123456"
    }
  ]
}
```

## Errors

* **401**: Not enough credits to create a list for the number of companies returned by the search (`Insufficient credits`), or Sales Navigator requirements are not met.
* **422**: Invalid combinations of growth parameters, disallowed extra parameters, invalid `department` type or value, or invalid optional filters (company size, locations, industries).

## Location IDs reference

Resolve IDs for `included_locations` and `excluded_locations` using the [Location Ids endpoint](/api-reference/endpoints/miscellaneous/location-ids).


## OpenAPI

````yaml POST /intents/accounts/growth
openapi: 3.0.1
info:
  title: Pipecorn Accounts API
  description: Pipecorn Accounts API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /intents/accounts/growth:
    post:
      summary: Create growth intent for accounts
      description: >-
        Start a LinkedIn account (company) search by growth criteria. Only
        documented fields are allowed; unknown keys return 422.


        **Valid criteria (choose one mode):**

        1. **Company-wide headcount growth:** Provide at least one of
        `min_headcount_growth_percentage` or `max_headcount_growth_percentage`.
        Do not send `department` in this mode.

        2. **Department metrics:** Send `department` (LinkedIn function ID as a
        string, e.g. `"1"`) plus at least one of `min_department_headcount`,
        `max_department_headcount`,
        `min_department_headcount_growth_percentage`, or
        `max_department_headcount_growth_percentage`.


        Department fields cannot be combined with company-wide headcount growth
        fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_url
              properties:
                webhook_url:
                  type: string
                  format: uri
                  description: >-
                    URL to receive growth intent results when processing
                    completes
                  example: https://your-company.com/webhooks/growth
                streaming:
                  type: boolean
                  description: >-
                    Whether to stream results to the webhook as they are
                    processed
                  example: false
                limit:
                  type: integer
                  minimum: 1
                  description: >-
                    Maximum number of companies to import. If omitted, import
                    volume is capped at 1000 even when the search finds more;
                    response `total` reflects the effective count
                  example: 500
                min_headcount_growth_percentage:
                  type: number
                  description: >-
                    Minimum company-wide headcount growth percentage (use with
                    or without `max_headcount_growth_percentage`; not valid
                    together with `department`)
                  example: 10
                max_headcount_growth_percentage:
                  type: number
                  description: >-
                    Maximum company-wide headcount growth percentage (use with
                    or without `min_headcount_growth_percentage`; not valid
                    together with `department`)
                  example: 50
                department:
                  type: string
                  description: >-
                    LinkedIn function ID to target (string, e.g. `"1"`).
                    Required when using any department headcount or department
                    growth field; must not be set together with company-wide
                    headcount growth fields
                  example: '1'
                min_department_headcount:
                  type: integer
                  description: >-
                    Minimum headcount in the selected department (requires
                    `department`)
                  example: 5
                max_department_headcount:
                  type: integer
                  description: >-
                    Maximum headcount in the selected department (requires
                    `department`)
                  example: 100
                min_department_headcount_growth_percentage:
                  type: number
                  description: >-
                    Minimum department headcount growth percentage (requires
                    `department`)
                  example: 15
                max_department_headcount_growth_percentage:
                  type: number
                  description: >-
                    Maximum department headcount growth percentage (requires
                    `department`)
                  example: 80
                company_size:
                  type: array
                  items:
                    type: string
                  description: >-
                    LinkedIn-style company size range strings (e.g. `51-200`).
                    Unicode en-dashes in values are normalized to hyphens on the
                    server
                  example:
                    - 51-200
                    - 201-500
                included_locations:
                  type: array
                  items:
                    type: integer
                  description: Location IDs to include
                  example:
                    - 103644278
                excluded_locations:
                  type: array
                  items:
                    type: integer
                  description: Location IDs to exclude
                  example: []
                included_industries:
                  type: array
                  items:
                    type: string
                  description: Industry IDs to include
                  example:
                    - '4'
      responses:
        '201':
          description: Search started; results are delivered to the webhook
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - id
                  - total
                  - preview
                properties:
                  message:
                    type: string
                    description: Confirmation that the account search started
                    example: >-
                      Account search started successfully. You will receive the
                      results on your webhook shortly.
                  id:
                    type: string
                    format: uuid
                    description: UUID of the import job
                    example: 5d4fabd2-e26d-47d1-b0de-4bf370f7b799
                  total:
                    type: integer
                    description: >-
                      Number of companies for this run: if `limit` is set, the
                      lesser of search size and `limit`; otherwise the full
                      search size (import may still cap at 1000)
                    example: 150
                  preview:
                    type: array
                    maxItems: 10
                    description: Up to 10 sample companies from the search
                    items:
                      type: object
                      properties:
                        company_name:
                          type: string
                          example: Acme Inc
                        industry:
                          type: string
                          example: Software Development
                        linkedin_id:
                          type: string
                          description: Numeric company ID extracted from the result
                          example: '123456'
                        linkedin_url:
                          type: string
                          format: uri
                          example: https://www.linkedin.com/company/123456
                  account_url:
                    type: string
                    format: uri
                    description: Present only in development environments (debugging)
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized (invalid API key, insufficient credits to create a list
            for the result size, or Sales Navigator requirements not met)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Unprocessable entity (invalid growth parameter combinations, unknown
            parameters, invalid `department`, or invalid optional filters)
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error payload shape varies; may include `error`, `message`,
                  `unauthorized_params`, `valid_combinations`,
                  `valid_departments`, etc.
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````