# Dataset Linkedin Company

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `POST` |
| **Endpoint** | `/v2/datasets/linkedin/company` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per row |
| **Documentation** | https://www.piloterr.com/library/datasets-linkedin-company |

## Description

Query the LinkedIn company dataset with Elasticsearch Query DSL. Filter by name, domain, industry, headcount, and country. POST-only, 1 credit per row returned.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request POST 'https://api.piloterr.com/v2/datasets/linkedin/company' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search by company name - WebAPI Group

```json
{
  "hits": [
    {
      "_id": "31",
      "_type": "_doc",
      "_index": "linkedin_company",
      "_score": 18.08,
      "_source": {
        "name": "WebAPI Group",
        "domain": "webapi.group",
        "founded": 2022,
        "tagline": "We elevate your business, one API at a time.",
        "website": "https://www.webapi.group/",
        "industry": "Software Development",
        "created_at": "2024-05-06T08:59:44.485+00:00",
        "updated_at": "2026-01-01T14:18:57.406+00:00",
        "description": "Unlock the full potential of web intelligence with our APIs.",
        "staff_count": 2,
        "staff_range": "1-10",
        "linkedin_url": "https://www.linkedin.com/company/webapi-group",
        "locations_list": [],
        "last_crawled_at": "2026-01-01T14:18:35.442+00:00",
        "headquarter_city": null,
        "headquarter_line1": null,
        "linkedin_id_alpha": "webapi-group",
        "specialities_list": [
          "API",
          "Scraping",
          "Web",
          "Web intelligence"
        ],
        "headquarter_country": null,
        "linkedin_id_numeric": 101119787,
        "headquarter_postal_code": null
      }
    }
  ],
  "total": 1,
  "max_score": 18.08,
  "search_metadata": {
    "credits": {
      "linkedin_company_count": 1
    },
    "account_id": "*",
    "account_name": "*"
  }
}
```

### Lookup by domain - openai.com

```json
{
  "hits": [
    {
      "_id": "2842",
      "_type": "_doc",
      "_index": "linkedin_company",
      "_score": 18.084406,
      "_source": {
        "name": "OpenAI",
        "domain": "openai.com",
        "founded": 2015,
        "tagline": "Creating safe AGI that benefits all of humanity.",
        "website": "https://openai.com/",
        "industry": "Research Services",
        "description": "OpenAI is an AI research and deployment company.",
        "staff_count": 3848,
        "staff_range": "1k-5k",
        "linkedin_url": "https://www.linkedin.com/company/openai",
        "headquarter_city": "San Francisco",
        "linkedin_id_alpha": "openai",
        "specialities_list": [
          "artificial intelligence machine learning"
        ],
        "headquarter_country": "US",
        "linkedin_id_numeric": 11130470
      }
    }
  ],
  "total": 34,
  "max_score": 18.084406
}
```

## Documentation

## Overview
The **LinkedIn Company Dataset API** queries the indexed LinkedIn company catalog (`linkedin_company`) with **Elasticsearch Query DSL**. Search and filter millions of company profiles by name, domain, industry, headcount, country, founding year, and more.

**POST-only.** Billing is **per row** (`per_row`): **1 credit per hit** returned in `hits[]`.

Use this endpoint for **bulk search, list building, and CRM enrichment at scale**. For a single live LinkedIn page scrape, use [LinkedIn Company Info](https://api.piloterr.com/v2/linkedin/company/info) (1 credit per call) instead.

## Quickstart
```
POST https://api.piloterr.com/v2/datasets/linkedin/company
Content-Type: application/json

{
  "query": {
    "bool": {
      "must": [{"match_phrase": {"name": "WebAPI Group"}}]
    }
  },
  "size": 10
}
```

Lookup by website domain:
```
POST https://api.piloterr.com/v2/datasets/linkedin/company
Content-Type: application/json

{
  "query": {"term": {"domain.keyword": "openai.com"}},
  "size": 1
}
```

## Request body
| Field | Type | Required | Description |
|---|---|---|---|
| `query` | object | yes | Elasticsearch Query DSL clause (see examples below) |
| `size` | integer | yes | Max rows to return (each row = 1 credit) |
| `sort` | array | no | Sort fields, e.g. `[{"staff_count": "desc"}]` |
| `from_` | integer | no | Pagination offset (0-based) |

## Query examples
| Use case | `query` body |
|---|---|
| Company name | `{"match_phrase": {"name": "OpenAI"}}` |
| Exact domain | `{"term": {"domain.keyword": "guideflow.com"}}` |
| LinkedIn ID | `{"match": {"linkedin_id_numeric": 7050}}` |
| Industry filter | `{"match": {"industry": "Software Development"}}` |
| Min headcount | `{"range": {"staff_count": {"gte": 500}}}` |
| Exclude small cos | `{"bool": {"must_not": [{"term": {"staff_range.keyword": "1-10"}}]}}` |

Wrap filters in `bool.must` / `bool.filter` / `bool.must_not` for complex searches.

## Response (`hits[]._source`)
| Field | Type | Description |
|---|---|---|
| `name` | string | Company display name |
| `domain` | string | Primary website domain |
| `website` | string | Full website URL |
| `industry` | string | LinkedIn industry label |
| `tagline` | string | Company tagline |
| `description` | string | About text |
| `staff_count` | integer | Declared employee count |
| `staff_range` | string | Size band (`1-10`, `1k-5k`, `over-10k`, ...) |
| `linkedin_url` | string | Canonical LinkedIn company URL |
| `linkedin_id_numeric` | integer | Numeric LinkedIn company ID |
| `linkedin_id_alpha` | string | LinkedIn slug / universal name |
| `headquarter_city` / `headquarter_country` | string | HQ location |
| `founded` | integer | Year founded |
| `specialities_list` | array | Speciality tags |
| `locations_list` | array | Office location strings |
| `last_crawled_at` | datetime | Last dataset refresh |

Top-level response also includes `total`, `max_score`, and `search_metadata.credits`.

## Dataset vs live scrape
| | **Dataset** (`/v2/datasets/linkedin/company`) | **Live** (`/v2/linkedin/company/info`) |
|---|---|---|
| Method | POST (ES query) | GET |
| Billing | 1 credit / row | 1 credit per call |
| Best for | Bulk search, filters, list building | One company, fresh page data |
| Query DSL | Yes | No |
| Live posts / employees | No | Yes (scraping endpoints) |

## Notes
- `size` is **required**, you always pay for rows returned, not empty searches.
- Use `domain.keyword` for exact domain matches (not analyzed `domain` text field).
- Indexed snapshot: fields may lag live LinkedIn; use LinkedIn Company Info when you need the current page.

## Main use cases
- Build ABM target lists filtered by industry, country, and headcount
- Enrich CRM domains with LinkedIn IDs, industry, and staff counts in bulk
- Resolve `linkedin_id_numeric` to firmographics for downstream profile enrichment
- Market mapping and competitive intelligence over the full company index