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

# Company Headcount API examples

> Ready-to-run Company Headcount API requests: current headcount by department, 12-month history, older history, headcount with the company profile, and searches for growing, shrinking, and department-heavy companies.

Each example on this page is one [Company Headcount API](https://docs.companyenrich.com/docs/company-headcount-api.md) request, shown in cURL, the four official SDKs, and the CLI. Every version sends the same request.

## Before you start

Create an API key at [app.companyenrich.com/access-keys](https://app.companyenrich.com/access-keys). The SDK examples assume a `client` created like this, with the key in the `COMPANYENRICH_API_KEY` environment variable:

```javascript JavaScript theme={null}
// npm install @companyenrich/sdk
import { CompanyEnrich } from '@companyenrich/sdk';

const client = new CompanyEnrich();
```

```python Python theme={null}
# pip install companyenrich
from companyenrich import CompanyEnrich

client = CompanyEnrich()
```

```ruby Ruby theme={null}
# gem install companyenrich
require "companyenrich"

client = CompanyEnrich::Client.new
```

```php PHP theme={null}
<?php
// composer require companyenrich/sdk
require 'vendor/autoload.php';

use CompanyEnrich\Client;

$client = new Client();
```

```bash CLI theme={null}
npm install -g @companyenrich/cli
companyenrich auth login
```

In the cURL examples, replace `YOUR_API_TOKEN` with your key.

## Get current headcount by department

Look up a company by domain. The response has the observed employee count, the estimated size range, and a headcount for each department. This costs 1 credit.

```bash cURL theme={null}
curl "https://api.companyenrich.com/v2/companies/workforce?domain=stripe.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript JavaScript theme={null}
const workforce = await client.companies.workforce({ domain: 'stripe.com' });

console.log(workforce.observedEmployeeCount, workforce.employeeCountRange);
console.log(workforce.departmentHeadcount.engineeringTechnical);
```

```python Python theme={null}
workforce = client.companies.workforce(domain="stripe.com")

print(workforce["observedEmployeeCount"], workforce.get("employeeCountRange"))
print(workforce["departmentHeadcount"].get("engineeringTechnical"))
```

```ruby Ruby theme={null}
workforce = client.companies.workforce(domain: "stripe.com")

puts workforce["observedEmployeeCount"], workforce["employeeCountRange"]
puts workforce.dig("departmentHeadcount", "engineeringTechnical")
```

```php PHP theme={null}
$workforce = $client->companies->workforce(domain: 'stripe.com');

echo $workforce['observedEmployeeCount'], ' ', $workforce['employeeCountRange'] ?? '', PHP_EOL;
echo $workforce['departmentHeadcount']['engineeringTechnical'] ?? '', PHP_EOL;
```

```bash CLI theme={null}
companyenrich company workforce stripe.com
```

To look up by CompanyEnrich ID in place of the domain, send `id` in cURL and JavaScript, `company_id` in Python and Ruby, and `companyId` in PHP. The CLI accepts either a domain or an ID as its argument.

## Read the last 12 months of history

The same response includes `history`: the months in the last year where headcount changed, newest first.

```bash cURL theme={null}
curl "https://api.companyenrich.com/v2/companies/workforce?domain=stripe.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript JavaScript theme={null}
const workforce = await client.companies.workforce({ domain: 'stripe.com' });

for (const point of workforce.history ?? []) {
  console.log(point.date, point.observedEmployeeCount);
}
```

```python Python theme={null}
workforce = client.companies.workforce(domain="stripe.com")

for point in workforce.get("history") or []:
    print(point["date"], point["observedEmployeeCount"])
```

```ruby Ruby theme={null}
workforce = client.companies.workforce(domain: "stripe.com")

(workforce["history"] || []).each do |point|
  puts "#{point['date']} #{point['observedEmployeeCount']}"
end
```

```php PHP theme={null}
$workforce = $client->companies->workforce(domain: 'stripe.com');

foreach ($workforce['history'] ?? [] as $point) {
    echo $point['date'], ' ', $point['observedEmployeeCount'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company workforce stripe.com --format csv -o headcount.csv
```

Each point has the `date` of the first day of its month, an `observedEmployeeCount`, and a `departmentHeadcount`.

## Go back further than 12 months

When older history exists, the response includes `nextCursor`. Send it as `cursor` to get the preceding 12 months. Each earlier page costs 1 credit.

```bash cURL theme={null}
# The latest 12 months. The response includes "nextCursor" when older history exists.
curl "https://api.companyenrich.com/v2/companies/workforce?domain=stripe.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# The 12 months before that
curl "https://api.companyenrich.com/v2/companies/workforce?domain=stripe.com&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript JavaScript theme={null}
const latest = await client.companies.workforce({ domain: 'stripe.com' });

if (latest.nextCursor) {
  const previousYear = await client.companies.workforce({
    domain: 'stripe.com',
    cursor: latest.nextCursor,
  });
  console.log(previousYear.historyFrom, previousYear.historyTo);
}
```

```python Python theme={null}
latest = client.companies.workforce(domain="stripe.com")

if latest.get("nextCursor"):
    previous_year = client.companies.workforce(
        domain="stripe.com",
        cursor=latest["nextCursor"],
    )
    print(previous_year["historyFrom"], previous_year["historyTo"])
```

```ruby Ruby theme={null}
latest = client.companies.workforce(domain: "stripe.com")

if latest["nextCursor"]
  previous_year = client.companies.workforce(
    domain: "stripe.com",
    cursor: latest["nextCursor"]
  )
  puts previous_year["historyFrom"], previous_year["historyTo"]
end
```

```php PHP theme={null}
$latest = $client->companies->workforce(domain: 'stripe.com');

if (isset($latest['nextCursor'])) {
    $previousYear = $client->companies->workforce(
        domain: 'stripe.com',
        cursor: $latest['nextCursor'],
    );
    echo $previousYear['historyFrom'], ' ', $previousYear['historyTo'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company workforce stripe.com --years 2
```

A cursor expires 30 minutes after the first page. In the CLI, `--years 2` fetches two pages for you.

## Get headcount with the company profile

The `workforce` expansion adds the same headcount data to a company record, so you get the profile and the headcount in one request. This enrichment costs 2 credits: 1 for the company and 1 for the expansion.

```bash cURL theme={null}
curl "https://api.companyenrich.com/v2/companies/enrich?domain=stripe.com&expand=workforce" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript JavaScript theme={null}
const company = await client.companies.enrich({ domain: 'stripe.com', expand: ['workforce'] });

console.log(company.name, company.workforce?.observedEmployeeCount);
console.log(company.workforce?.departmentHeadcount);
```

```python Python theme={null}
company = client.companies.enrich("stripe.com", expand=["workforce"])

workforce = company.get("workforce") or {}
print(company.get("name"), workforce.get("observedEmployeeCount"))
print(workforce.get("departmentHeadcount"))
```

```ruby Ruby theme={null}
company = client.companies.enrich("stripe.com", expand: ["workforce"])

puts company["name"], company.dig("workforce", "observedEmployeeCount")
p company.dig("workforce", "departmentHeadcount")
```

```php PHP theme={null}
$company = $client->companies->enrich('stripe.com', expand: ['workforce']);

echo $company['name'] ?? '', ' ', $company['workforce']['observedEmployeeCount'] ?? '', PHP_EOL;
print_r($company['workforce']['departmentHeadcount'] ?? []);
```

```bash CLI theme={null}
companyenrich company enrich stripe.com --expand workforce
```

The expansion also works on company search, batch enrichment, and bulk enrichment, at 1 extra credit per company.

## Find companies that are growing

The `workforceGrowth` filter on company search matches headcount change over a period. This search finds SaaS companies in the United States whose headcount grew at least 20% in the last year.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "categories": "saas",
      "country": "US",
      "workforceGrowth": {"period": "y1", "min": 0.2}
    },
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const page = await client.companies.search({
  filter: {
    categories: 'saas',
    country: 'US',
    workforceGrowth: { period: 'y1', min: 0.2 },
  },
  pageSize: 25,
});

for (const company of page.items) {
  console.log(company.name, company.domain);
}
```

```python Python theme={null}
page = client.companies.search(
    filter={
        "categories": "saas",
        "country": "US",
        "workforceGrowth": {"period": "y1", "min": 0.2},
    },
    page_size=25,
)

for company in page["items"]:
    print(company.get("name"), company["domain"])
```

```ruby Ruby theme={null}
page = client.companies.search(
  filter: {
    categories: "saas",
    country: "US",
    workforceGrowth: { period: "y1", min: 0.2 }
  },
  page_size: 25
)

page["items"].each do |company|
  puts "#{company['name']} (#{company['domain']})"
end
```

```php PHP theme={null}
$page = $client->companies->search(
    filter: [
        'categories' => 'saas',
        'country' => 'US',
        'workforceGrowth' => ['period' => 'y1', 'min' => 0.2],
    ],
    pageSize: 25,
);

foreach ($page['items'] as $company) {
    echo $company['name'] ?? '', ' ', $company['domain'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company search --category saas --country US --growth 20%.. --growth-period y1 --limit 25
```

`period` is `m6`, `y1`, or `y2`, for 6 months, 1 year, or 2 years. A ratio of `0.2` means 20%. The search costs 1 credit per company, with no extra charge for the filter.

## Find companies that are shrinking

A negative growth ratio means headcount fell. This search finds companies with 201 to 1,000 employees whose headcount dropped 10% or more in the last 6 months.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "employees": ["201-500", "501-1K"],
      "workforceGrowth": {"period": "m6", "max": -0.1}
    },
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const page = await client.companies.search({
  filter: {
    employees: ['201-500', '501-1K'],
    workforceGrowth: { period: 'm6', max: -0.1 },
  },
  pageSize: 25,
});

for (const company of page.items) {
  console.log(company.name, company.domain);
}
```

```python Python theme={null}
page = client.companies.search(
    filter={
        "employees": ["201-500", "501-1K"],
        "workforceGrowth": {"period": "m6", "max": -0.1},
    },
    page_size=25,
)

for company in page["items"]:
    print(company.get("name"), company["domain"])
```

```ruby Ruby theme={null}
page = client.companies.search(
  filter: {
    employees: ["201-500", "501-1K"],
    workforceGrowth: { period: "m6", max: -0.1 }
  },
  page_size: 25
)

page["items"].each do |company|
  puts "#{company['name']} (#{company['domain']})"
end
```

```php PHP theme={null}
$page = $client->companies->search(
    filter: [
        'employees' => ['201-500', '501-1K'],
        'workforceGrowth' => ['period' => 'm6', 'max' => -0.1],
    ],
    pageSize: 25,
);

foreach ($page['items'] as $company) {
    echo $company['name'] ?? '', ' ', $company['domain'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company search --employees 201-500,501-1K --growth ..-10% --growth-period m6 --limit 25
```

## Find companies by department size

The `workforceSize` filter matches headcount ranges, overall or for one department. This search finds companies in Germany with at least 50 people in engineering.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "country": "DE",
      "workforceSize": [{"department": "engineering_technical", "min": 50}]
    },
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const page = await client.companies.search({
  filter: {
    country: 'DE',
    workforceSize: [{ department: 'engineering_technical', min: 50 }],
  },
  pageSize: 25,
});

for (const company of page.items) {
  console.log(company.name, company.domain);
}
```

```python Python theme={null}
page = client.companies.search(
    filter={
        "country": "DE",
        "workforceSize": [{"department": "engineering_technical", "min": 50}],
    },
    page_size=25,
)

for company in page["items"]:
    print(company.get("name"), company["domain"])
```

```ruby Ruby theme={null}
page = client.companies.search(
  filter: {
    country: "DE",
    workforceSize: [{ department: "engineering_technical", min: 50 }]
  },
  page_size: 25
)

page["items"].each do |company|
  puts "#{company['name']} (#{company['domain']})"
end
```

```php PHP theme={null}
$page = $client->companies->search(
    filter: [
        'country' => 'DE',
        'workforceSize' => [['department' => 'engineering_technical', 'min' => 50]],
    ],
    pageSize: 25,
);

foreach ($page['items'] as $company) {
    echo $company['name'] ?? '', ' ', $company['domain'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company search --country DE --headcount engineering_technical=50.. --limit 25
```

Add more entries to `workforceSize` to set several ranges at once. Department names in the workforce filters use underscores, such as `engineering_technical`.

## Related pages

> [card] [Company Headcount API](https://docs.companyenrich.com/docs/company-headcount-api.md)
>
> Response fields, history paging, pricing, and limits.

> [card] [Company Search API filters](https://docs.companyenrich.com/docs/company-search-api-filters.md#workforce)
>
> The headcount and growth filters in full.

> [card] [Company Enrichment API examples](https://docs.companyenrich.com/docs/company-enrichment-api-examples.md)
>
> Enrich companies with expansions, in batches or in bulk.

> [card] [Credits](https://docs.companyenrich.com/docs/credits.md)
>
> What each lookup and expansion costs.


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