ACTION_ID: people_count_by_filters
NAME: People count with filters
CATEGORY: Company Enrichment
CREDITS: 0.1

Count how many people in Floqer's own people database match a
combination of company and job filters — a bare number, no records
pulled.
Flat 0.1 credits per call regardless of how large the result is,
so it's cheap to use as an account-level signal (e.g. "does this
company have more than 50 engineers in the US?") without fanning
out to a per-employee list.

1. INPUTS

At least one filter field is required — an unfiltered count against
the full 400M+ record database is rejected with a 400.

company_domain (type: string, optional) — Company Domain
  Exact match. Accepts a bare domain, a full URL, or a "www."
  domain — normalized to the bare lowercase domain before matching
  (e.g. "https://www.Acme.com/pricing" -> "acme.com"). An
  unparseable value is rejected with a 400.

company_name (type: string, optional) — Company Name
  Partial (contains) match. Must not contain any of the filter
  syntax's reserved characters: , | ( ) = ! < > ^ $ * — rejected
  with a 400 if it does.

company_linkedin_url (type: string, optional) — Company LinkedIn URL
  Exact match. Accepts any LinkedIn company URL shape (with or
  without scheme/www, trailing slash, or a bare slug like "google")
  — normalized to the canonical
  "https://www.linkedin.com/company/<slug>" form before matching.
  A person-profile or school URL, or anything that isn't a company
  LinkedIn URL, is rejected with a 400.

job_title (type: string, optional) — Job Title
  Partial (contains) match against job title, e.g. "Engineer".
  Same reserved-character restriction as company_name.

job_location_country (type: multi-select array, optional) — Job Location Country
  One or more countries, OR-matched. Values are matched
  case-insensitively and case-corrected before matching, but must
  match one of the accepted country names — an unrecognized value
  is rejected with a 400 listing the bad value(s). Fetch the full
  accepted list via Get Action Field Options (see KEY NOTES) rather
  than guessing spellings.

job_function (type: multi-select array, optional) — Job Function
  One or more job functions, OR-matched, from a closed list (e.g.
  "Engineering", "Sales & Business Development", "Human
  Resources"). Same case-insensitive matching / 400-on-unknown-value
  behavior as job_location_country. Fetch the full list via Get
  Action Field Options.

job_level (type: multi-select array, optional) — Job Level
  One or more seniority levels, OR-matched, from a closed list:
  "C-Team", "Director", "Manager", "Other", "Staff", "VP". Same
  case-insensitive matching / 400-on-unknown-value behavior.

job_location_city (type: string, optional) — Job Location City
  Partial (contains) match. Comma-separates multiple cities,
  OR-matched, e.g. "London, Manchester". Do NOT put a comma inside
  a single city name — comma is the multi-value separator here, so
  "Washington, D.C." is parsed as two clauses ("Washington" and a
  dangling "D.C."), not one. Enter "Washington DC" instead. Every
  other reserved character (| ( ) = ! < > ^ $ *) is still rejected
  with a 400.

job_location_state (type: string, optional) — Job Location State
  Partial (contains) match. Comma-separates multiple states,
  OR-matched, e.g. "California, Texas". Same comma-is-a-separator
  caveat as job_location_city — don't put a literal comma inside a
  single state name.

2. OUTPUTS

total_records (type: number) — Total Records
  Count of people matching the given filters.

count_capped (type: boolean) — Count Capped
  True if the count hit the database's own max-count cap and
  total_records is therefore not exact (a floor, not the real
  total).

3. HOW TO CONFIGURE

Configure Action body:

{
  "inputs": {
    "company_domain": "{{input.company_domain}}",
    "job_function": ["Engineering"],
    "job_level": ["Director", "VP"],
    "job_location_country": ["Ireland"]
  }
}

Field-by-field:
  - company_domain          Optional exact-match company filter.
  - company_name            Optional partial-match company filter.
  - company_linkedin_url     Optional exact-match company LinkedIn URL filter.
  - job_title                Optional partial-match title filter.
  - job_location_country     Optional multi-select country filter.
  - job_function              Optional multi-select function filter.
  - job_level                 Optional multi-select seniority filter.
  - job_location_city         Optional comma-separated city filter.
  - job_location_state        Optional comma-separated state filter.

At least one of the nine must be set.

4. KEY NOTES

- Enum fields (job_location_country, job_function, job_level) are
  validated server-side against a closed list — a value outside
  the list is rejected with a 400 before any credits are
  consumed. Fetch the current accepted values with Get Action
  Field Options (`POST .../actions/:action_instance_id/options/job_function`,
  `/job_level`, `/job_location_country`) rather than hard-coding a
  list in your integration — they come straight from the action's
  own definition, so they can't drift out of date.
- company_domain match is EXACT, not partial — "acme.com" will not
  match a person whose company_domain is stored as
  "app.acme.com". Use company_name (partial match) if you're not
  sure of the exact registered domain.
- company_linkedin_url match is also EXACT (against the normalized
  canonical URL), same caveat as company_domain — use company_name
  (partial match) if you're not sure of the exact LinkedIn URL.
- job_location_city / job_location_state accept multiple
  comma-separated values but do NOT accept a literal comma inside
  one value (see field notes above) — the underlying filter syntax
  has no quoting/escaping mechanism, so there's no way to pass a
  comma-containing place name through safely.
- count_capped signals an inexact (floored) total_records — check
  it before treating the count as a precise number, especially for
  very broad filters.
- Billing is flat (0.1 credits) regardless of result size — cheaper
  to use as an account-level headcount signal than a full employee
  finder (e.g. get_employees_by_company_using_floqer_native) when
  you only need the number, not the people.

5. WHERE IT FITS IN A WORKFLOW

Pattern (account-level headcount signal): use as a cheap filter or
score on a target-account list before spending credits on a full
per-employee finder.

  input (target company — domain or name)
    -> people_count_by_filters (job_function / job_level /
       job_location_country set to the ICP definition)
    -> filter (only continue rows where total_records
       clears your minimum headcount threshold)
    -> get_employees_by_company_using_floqer_native (fan out to
       actual people only for accounts that passed the filter).

6. WHEN TO USE

Use people_count_by_filters when you need a number — "how many
people at this company match these criteria?" — without pulling
the underlying person records.

7. WHEN NOT TO USE

Need the actual list of matching people, not just a count
  -> action-detail/get_employees_by_company_using_floqer_native.txt
  That action returns per-employee records (name, LinkedIn URL,
  title, country) for a target company, with the same kind of
  title / seniority / country filters.

Need a per-country or per-role headcount breakdown for one
specific company, not a filtered count across the whole database
  -> action-detail/company_headcount_distribution_by_country.txt
  and action-detail/company_headcount_distribution_by_job_role.txt
  Those return a distribution for one named company; this action
  answers "how many people anywhere match these filters", scoped
  down to one company only when you also set company_domain /
  company_name / company_linkedin_url.

Last updated: 2026-09-02.