> ## 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 people at company

> Searches for leads based on job titles and a company (LinkedIn company ID or URL). Optionally narrow results by location, LinkedIn **function** (department), and **seniority** level using the authorized ID lists below.

By default the search runs live through LinkedIn (`live: true`) and requires a connected integration. Set `live: false` to resolve the company and matching people from Pipecorn's people database (Elasticsearch) instead, with no LinkedIn call and no integration required.

# Find 2x people than with Clay

* Input : Job titles + Company
* Output : Live matching people data

<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0 }}>
  <iframe
    src="https://www.tella.tv/video/cmieh89m7000s04i99tox22nk/embed?b=0&title=0&a=0&loop=0&t=0&muted=0&wt=0"
    style={{
  position: 'absolute',
  top: 0,
  left: 0,
  width: '100%',
  height: '100%',
  border: 0
}}
    allowFullScreen
    allowTransparency
    title="Pipecorn API Overview"
  />
</div>

# Prerequisites

## In Pipecorn

* A Pipecorn account with API access
* A valid **[sync](https://app.pipecorn.com/settings/extension)**
* Your Pipecorn **API key** ([How to get your API key](/api-reference/API-key))

## In Clay

A **Companies** table with at least:

* Company Name
* Domain
* Company LinkedIn URL (or LinkedIn Org ID)

These fields tell Pipecorn which company to search on LinkedIn.

# Step 1 — Create a Webhook Table in Clay

Pipecorn needs an endpoint to “deliver” the people it finds.

We’ll use a **Monitor Webhook** table.

1. In Clay, click **Add** → **Monitor Webhook**
2. Clay creates a new table with a **Webhook column**
3. Click the **Webhook column** → **Sources** → **Pull data from webhook**
4. Copy the **Webhook URL**

You will paste this URL into Pipecorn’s API request later.

# Step 2 — Add an HTTP API Column to Your Companies Table

1. Go back to your **Companies** table
2. Click **Add Column**
3. Choose **Add Enrichment**
4. Select **HTTP API**

This is the column that will call Pipecorn’s Find People API for each company.

# Step 3 — Configure the API Call

### Method

`POST`

### Endpoint

```
https://app.pipecorn.com/api/v2/leads/search
```

### Body (JSON)

Paste this JSON and customize it as needed:

```json theme={null}
{
  "name": "Find people at {{Company Name}}",
  "webhook_url": "PASTE_YOUR_WEBHOOK_URL_HERE",
  "company_linkedin_url": "{{Company Linkedin URL}}",
  "job_titles": [
    "Head of Talent",
    "HR Director",
    "Talent Acquisition Manager"
  ],
  "excluded_job_titles": [
    "Intern"
  ],
  "functions": ["12", "15"],
  "seniority_levels": ["220", "300"],
  "streaming": true,
  "limit": 50
}

```

#### Using a saved Persona instead of inlining job titles

If you've already defined a Persona in Pipecorn, you can reference it by `persona_id`. Pipecorn will use that persona's included and excluded job titles automatically — do **not** pass `job_titles` or `excluded_job_titles` alongside `persona_id`.

```json theme={null}
{
  "name": "Find people at {{Company Name}}",
  "webhook_url": "PASTE_YOUR_WEBHOOK_URL_HERE",
  "company_linkedin_url": "{{Company Linkedin URL}}",
  "persona_id": "1f6b0f5a-2d8e-4c3a-9b8f-1a2b3c4d5e6f",
  "streaming": true,
  "limit": 50
}
```

> **At least one people filter is required.** The request must include at least one of `job_titles`, `excluded_job_titles`, `functions`, `seniority_levels`, `included_locations`, `excluded_locations`, or `persona_id`. Requests with none of these return `400`.

### Field explanations

* **name**: Label used inside Pipecorn
* **webhook\_url**: Clay webhook URL (Step 1)
* **company\_linkedin\_url**: Clay variable for the company’s LinkedIn profile
* **job\_titles**: The personas you want to target. If you pass `[*]` we will return every person in the company, regardless of their job title.
* **excluded\_job\_titles**: Optional list
* **persona\_id** (optional): UUID of a Pipecorn Persona. When provided, `job_titles` and `excluded_job_titles` are taken from the persona definition and **must not** be passed in the request — doing so returns `422`. Use this when you want a saved persona to drive the search instead of inlining job titles.
* **included\_locations** (optional): If used, we will return only leads with matching location. Location ids can be retrieved via this [endpoint](/api-reference/endpoints/miscellaneous/location-ids).
* **excluded\_locations** (optional): Location IDs to exclude (same ID source as above).
* **functions** (optional): Array of LinkedIn function IDs (department / job function). Only the IDs listed in [Authorized function IDs](#authorized-function-ids) are accepted. Multiple values use OR logic.
* **seniority\_levels** (optional): Array of LinkedIn seniority level IDs. Only the IDs listed in [Authorized seniority level IDs](#authorized-seniority-level-ids) are accepted. Multiple values use OR logic.
* **streaming**: Sends results to Clay row by row
* **limit**: Max number of people to return per company
* **live** (optional, boolean): Data source. Defaults to `true`, which searches LinkedIn in real time using your synced session. Set to `false` to resolve the company and matching people from Pipecorn's people database instead — no live LinkedIn call and no synced session required. A non-boolean value returns `422`.

If `functions` or `seniority_levels` is present, it must be a JSON array. Invalid IDs return `422` with a message listing the invalid values and the full set of valid IDs.

### Authorized function IDs

| ID | Label                            |
| -- | -------------------------------- |
| 1  | Accounting                       |
| 2  | Administrative                   |
| 3  | Arts and Design                  |
| 4  | Business Development             |
| 5  | Community and Social Services    |
| 6  | Consulting                       |
| 7  | Education                        |
| 8  | Engineering                      |
| 9  | Entrepreneurship                 |
| 10 | Finance                          |
| 11 | Healthcare Services              |
| 12 | Human Resources                  |
| 13 | Information Technology           |
| 14 | Legal                            |
| 15 | Marketing                        |
| 16 | Media and Communication          |
| 17 | Military and Protective Services |
| 18 | Operations                       |
| 19 | Product Management               |
| 20 | Program and Project Management   |
| 21 | Purchasing                       |
| 22 | Quality Assurance                |
| 23 | Real Estate                      |
| 24 | Research                         |
| 25 | Sales                            |
| 26 | Customer Success and Support     |

### Authorized seniority level IDs

| ID  | Label               |
| --- | ------------------- |
| 100 | In Training         |
| 110 | Entry Level         |
| 120 | Senior              |
| 130 | Strategic           |
| 200 | Entry Level Manager |
| 210 | Experienced Manager |
| 220 | Director            |
| 300 | Vice President      |
| 310 | CXO                 |
| 320 | Owner / Partner     |

Click **Save & Don’t Run**.

> **Clay JSON formatting errors?** Double-check commas, spacing, or [copy our template](https://app.clay.com/shared-workbook/share_0swi80wycWeW9mHM64p) to fix issues.

### Headers

| Key       | Value                 |
| --------- | --------------------- |
| X-API-KEY | Your Pipecorn API key |

# Step 4 — Run Your First Find People Request

1. In your **Companies** table
2. Go to your new **HTTP API** column
3. Click the **▶️ Play** button on any company row

Pipecorn will immediately:

* query LinkedIn for your persona
* extract matching profiles
* stream the results into your Webhook table

# Step 5 — View and Use the Results

Go to your **Webhook table**.

You’ll see people appear row by row as Pipecorn finds them.

Click **Add Column** → search and add:

* `full_name`
* `title`
* `linkedin_url`
* `linkedin_id`
* `company_name`
* `status`
* `rejection_reasons`

You now have a **live Find People pipeline** inside Clay.

# FAQ

### Does this use my Clay credits?

No, Pipecorn handles the search, so you don’t use any Clay Find People credits.

### Is the data live?

Yes, by default Pipecorn searches in real-time using your synced session. If you'd rather not depend on a synced session — or want faster, integration-free results — pass `live: false` to search Pipecorn's people database instead.

### Can I run this at scale?

Yes, You can run it on thousands of companies. Pipecorn streams results progressively to avoid rate limits.

### What if my sync breaks?

Just re-sync your account in Pipecorn Settings.

# Need help?

If you need help customizing your Find people, please book a 15min set up with me : [https://zcal.co/mathieu-pipecorn/enterprise](https://zcal.co/mathieu-pipecorn/enterprise)

# Want to scale further ?

The `scale` parameter (boolean, optional) allows you to increase your volume of requests by omitting the following fields:

* `connections_count`
* `headline`
* Vanity LinkedIn profile URL (like `https://www.linkedin.com/in/mathieu-brun-picard/`)

When `scale` is set to `true`, you will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL format (like `https://linkedin.com/in/ACwAACaX8uYBfAh-5YxmfObz4mVOKYih3zxa-TM`).


## OpenAPI

````yaml POST /leads/search
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:
  /leads/search:
    post:
      summary: Search leads by job title for a specific company
      description: >-
        Searches for leads based on job titles and a company (LinkedIn company
        ID or URL). Optionally narrow results by location, LinkedIn **function**
        (department), and **seniority** level using the authorized ID lists
        below.


        By default the search runs live through LinkedIn (`live: true`) and
        requires a connected integration. Set `live: false` to resolve the
        company and matching people from Pipecorn's people database
        (Elasticsearch) instead, with no LinkedIn call and no integration
        required.
      requestBody:
        description: Parameters for lead search by job title
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the lead search
                  example: Software Engineer Search
                webhook_url:
                  type: string
                  description: >-
                    Optional webhook URL to receive results when the search is
                    complete
                  example: https://example.com/webhook
                company_linkedin_id:
                  type: string
                  description: >-
                    The LinkedIn ID of the company (required if
                    company_linkedin_url is not provided)
                  example: '1234567890'
                company_linkedin_url:
                  type: string
                  format: uri
                  description: >-
                    The LinkedIn URL of the company. Required if
                    company_linkedin_id is not provided)
                  example: https://www.linkedin.com/company/pipecorn
                job_titles:
                  type: array
                  items:
                    type: string
                  description: >-
                    List of job titles to search for. Cannot be combined with
                    `persona_id` — pass one or the other.
                  example:
                    - Software Engineer
                    - Product Manager
                excluded_job_titles:
                  type: array
                  items:
                    type: string
                  description: >-
                    List of job titles to exclude from the search. Cannot be
                    combined with `persona_id` — pass one or the other.
                  example:
                    - Intern
                    - Contractor
                persona_id:
                  type: string
                  format: uuid
                  description: >-
                    Optional. UUID of a saved Pipecorn Persona. When provided,
                    `job_titles` and `excluded_job_titles` are derived from the
                    persona and must not be passed in the request — doing so
                    returns `422`. The persona must belong to the authenticated
                    user.
                  example: 1f6b0f5a-2d8e-4c3a-9b8f-1a2b3c4d5e6f
                included_locations:
                  type: array
                  items:
                    type: string
                  description: List of Location IDs that were included in the search
                  example:
                    - '105015875'
                    - '102221843'
                excluded_locations:
                  type: array
                  items:
                    type: string
                  description: List of Location IDs that were excluded from the search
                  example:
                    - '103644278'
                functions:
                  type: array
                  items:
                    type: string
                    enum:
                      - '1'
                      - '2'
                      - '3'
                      - '4'
                      - '5'
                      - '6'
                      - '7'
                      - '8'
                      - '9'
                      - '10'
                      - '11'
                      - '12'
                      - '13'
                      - '14'
                      - '15'
                      - '16'
                      - '17'
                      - '18'
                      - '19'
                      - '20'
                      - '21'
                      - '22'
                      - '23'
                      - '24'
                      - '25'
                      - '26'
                  description: >-
                    Optional. Filter by LinkedIn function (job function /
                    department). Each value must be one of the authorized
                    function IDs below. Omit or pass an empty array to not
                    filter by function. Multiple IDs are combined with OR logic.


                    ID → value: 1 Accounting; 2 Administrative; 3 Arts and
                    Design; 4 Business Development; 5 Community and Social
                    Services; 6 Consulting; 7 Education; 8 Engineering; 9
                    Entrepreneurship; 10 Finance; 11 Healthcare Services; 12
                    Human Resources; 13 Information Technology; 14 Legal; 15
                    Marketing; 16 Media and Communication; 17 Military and
                    Protective Services; 18 Operations; 19 Product Management;
                    20 Program and Project Management; 21 Purchasing; 22 Quality
                    Assurance; 23 Real Estate; 24 Research; 25 Sales; 26
                    Customer Success and Support.
                  example:
                    - '13'
                    - '15'
                seniority_levels:
                  type: array
                  items:
                    type: string
                    enum:
                      - '100'
                      - '110'
                      - '120'
                      - '130'
                      - '200'
                      - '210'
                      - '220'
                      - '300'
                      - '310'
                      - '320'
                  description: >-
                    Optional. Filter by LinkedIn seniority level. Each value
                    must be one of the authorized seniority IDs below. Omit or
                    pass an empty array to not filter by seniority. Multiple IDs
                    are combined with OR logic.


                    ID → value: 100 In Training; 110 Entry Level; 120 Senior;
                    130 Strategic; 200 Entry Level Manager; 210 Experienced
                    Manager; 220 Director; 300 Vice President; 310 CXO; 320
                    Owner / Partner.
                  example:
                    - '220'
                    - '300'
                streaming:
                  type: boolean
                  description: >-
                    When set to true, leads will be sent individually to the
                    webhook_url as they are found. This is ideal for integration
                    with platforms like Clay that process leads in real-time.
                  default: false
                  example: true
                custom:
                  type: object
                  description: >-
                    Custom fields to include with the lead search that will be
                    returned in the webhook (like crm id, etc.)
                  additionalProperties: true
                  example:
                    hubspot_id: '134567'
                limit:
                  type: integer
                  description: >-
                    Optional parameter to limit the number of results returned.
                    If not specified, all matching leads will be returned.
                  minimum: 1
                  example: 100
                scale:
                  type: boolean
                  description: >-
                    When set to true, increases request volume by omitting the
                    following fields: connections_count, headline, and vanity
                    LinkedIn profile URL. You will still receive a LinkedIn
                    profile URL, but it will use the user ID instead of the
                    vanity URL (e.g.,
                    https://www.linkedin.com/in/mathieu-brun-picard/).
                  default: false
                  example: true
                live:
                  type: boolean
                  description: >-
                    Data source toggle. `true` (default) runs the search live
                    through LinkedIn and requires a connected integration.
                    `false` resolves the company and matching people from
                    Pipecorn's people database (Elasticsearch) instead and
                    streams them to your webhook, with no LinkedIn call and no
                    integration required. A non-boolean value returns `422`.
                  default: true
                  example: true
              allOf:
                - oneOf:
                    - required:
                        - company_linkedin_id
                    - required:
                        - company_linkedin_url
                - anyOf:
                    - required:
                        - job_titles
                    - required:
                        - excluded_job_titles
                    - required:
                        - functions
                    - required:
                        - seniority_levels
                    - required:
                        - included_locations
                    - required:
                        - excluded_locations
                    - required:
                        - persona_id
      responses:
        '201':
          description: Search initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The ID of the created lead search
                  search_name:
                    type: string
                    description: Name of the lead search
                  search_url:
                    type: string
                    format: uri
                    description: The LinkedIn search URL used for extraction
                  created_at:
                    type: string
                    format: date-time
                    description: When the search was created
                  custom:
                    type: object
                    description: Custom attributes included with the search
                    additionalProperties: true
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - API key doesn't have the required permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Validation error — for example `functions` or `seniority_levels`
            must be arrays, or they contain IDs that are not in the authorized
            lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable validation message
                    example: >-
                      Invalid function IDs: 99. Valid IDs are: 1, 2, 3, 4, 5, 6,
                      7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21,
                      22, 23, 24, 25, 26
        '429':
          description: Rate limit exceeded (1 request per 5 seconds)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      description: Your API key
      name: X-API-KEY

````