Track Company Headcount Over Time With an API
By Kooperativa Engineering
To track a company's headcount over time with an API, store a dated snapshot of its headcount on a schedule and compare the snapshots. Our API returns the current figures for a company, so the history is one you build. That is a deliberate trade: you choose the interval, the field and the definition, and every point in the series was measured the same way.
Some providers sell a ready-made monthly series, which is convenient when it fits your definition of headcount. This article covers the build-it-yourself route: what to store, what to watch for in the numbers, and when a monitor is a better tool than a schedule.
What one snapshot contains
The headcount by seniority endpoint takes a company identifier and returns total_indexed plus a breakdown across five bands, from c-level down to individual contributors. The bands add up to the total exactly, because the individual band is derived from what is left after the four named levels. It is a single request per company.
total_indexed counts the profiles in the index that list the company as their current employer. It is not payroll headcount. The article on finding a company's employee count explains why the two numbers differ, and why that is fine for a trend as long as the definition stays the same from one snapshot to the next.
const headers = { Authorization: 'Bearer ' + process.env.KOOPERATIVA_API_KEY };
const companyIds = ['<company_id>', '<company_id>'];
const today = new Date().toISOString().slice(0, 10);
const rows = [];
for (const id of companyIds) {
const res = await fetch(
'https://kooperativa.io/api/v1/company/headcount-by-seniority?company_id=' + id,
{ headers }
);
if (!res.ok) continue; // leave a gap, never write a zero
const data = await res.json();
rows.push({ date: today, company_id: id, total: data.total_indexed, breakdown: data.breakdown });
}
// append rows to your own table: one row per company per runRead the series with the refresh cycle in mind
Our terms describe source data as refreshed on a cycle of up to 90 days. A change inside a company can therefore take up to that long to show up, and a step between two snapshots may reflect a refresh rather than a hiring week. You can snapshot weekly, but read the trend over quarters, not week to week.
Three habits keep the series trustworthy. Store the breakdown as well as the total, because a flat total can hide a shift between bands. Record a failed call as a gap, because a zero looks like a collapse. And keep the same company identifier for every run, so a rename or a changed domain never splits one company into two lines.
Use a monitor when you care about the change, not the line
If what you need is to know when something changes, a monitor is the better tool. You subscribe to a person or company URL, and a signed webhook arrives when a change is detected, so there is nothing to poll and nothing to diff. A schedule gives you a chart. A monitor gives you the moment.
Cross-check a movement with hiring and departures
Two other calls help explain a movement in the series. The hiring signals endpoint returns recent job changes among the people at a company, over 90 days by default and up to 365. The past employees endpoint returns people who have left, with the role they held there.
A rising total together with many recent job changes points to hiring. A flat total together with a long list of past employees can point to churn that hiring is masking. Neither call replaces the snapshot series, they explain it.
When to buy a ready-made series instead
A series you build starts the day you start it. If you need years of history on day one, it cannot give you that. In that case compare providers that publish a historical series, and check what the series counts, how often it is sampled and whether it covers private companies. The post Best Employee Data APIs Compared lists what several providers state on their public pages.
Frequently asked questions
Does Kooperativa return historical headcount?
No. The company and headcount endpoints return current figures. A history is built by storing dated snapshots, as described above.
How often should I take a snapshot?
Weekly or monthly is enough for most teams. Source records refresh on a cycle of up to 90 days, so a faster schedule mostly records the same value.
Is total_indexed the official headcount of a company?
No. It counts indexed profiles that list the company as the current employer, which is a different number from payroll or a regulatory filing.
Get started
Try Kooperativa
One API key. Person and company enrichment, structured search, and monitors under one flat license.