ACTION_ID: company_headcount_distribution_by_country
NAME: Company Headcount by Country
CATEGORY: scrape
CREDITS: 1

Get the number of employees at a company, categorized by country.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

company_identifier (type: string, required) — Company Identifier
  Identifier for the company to look up. Accepts a company name,
  domain, or LinkedIn URL.

================================================================================
2. OUTPUTS
================================================================================

company_headcount (type: number) — Company Headcount
  Total employee count at the company.

company_headcount_by_country (type: raw_array) — Company Headcount By Country
  Per-country breakdown of the employee count.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body:

{
  "inputs": {
    "company_identifier": "{{input.company_domain}}"
  }
}

Pass a company name, domain, or LinkedIn URL as
`company_identifier`.

Identifier preference: prefer the company domain or LinkedIn URL
when available. The action will accept a plain company name, but
common / generic / similarly-named companies may resolve to the
wrong record (e.g. "Acme" could match many distinct companies).
Domain and LinkedIn URL are unique identifiers and produce
deterministic matches; fall back to company name only when neither
is available.

================================================================================
4. KEY NOTES
================================================================================

- `company_headcount_by_country` is a nested raw_array — extract
  per-country values via `format_data_using_js_expression` if you
  need them as flat columns (e.g. percentage of headcount in the
  target region as a single number).
- For workforce trends beyond country distribution (growth rate,
  hiring velocity, role mix), use `company_enrich_using_people_data_labs`
  — it returns the country breakdown plus the full PDL workforce
  dataset.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern (geographic ICP filter): use the per-country headcount
breakdown to score or filter companies by where their workforce
actually sits — useful when your ICP is region-specific (e.g.
"target US-only companies" or "companies with > 30% APAC
headcount").

  input (company name, domain, or LinkedIn URL)
    -> company_headcount_distribution_by_country (returns
       company_headcount + company_headcount_by_country)
    -> format_data_using_js_expression (extract / score the
       country distribution into a clean field — e.g. percent
       of headcount in target region)
    -> filter / outreach prioritization.

================================================================================
6. WHEN TO USE
================================================================================

Use company_headcount_distribution_by_country to surface a company's
geographic employee distribution.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need general firmographics, or workforce trends by role / over
time — beyond just country headcount distribution
  -> company_enrich_using_people_data_labs
     (https://floqer.com/docs/action-detail/company_enrich_using_people_data_labs.txt)
  PDL's company enrich returns the country headcount distribution
  too, plus broader firmographics (industry, revenue, funding,
  technologies) and workforce-trend fields like
  employee_count_by_job_role, average_tenure_by_role, and
  employee_growth_rate. Use this action when you only need the
  country breakdown and want the lighter call; reach for PDL when
  you need the full company picture.

================================================================================

This file is maintained manually. Last updated: 2026-04-30.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt