Company data

Every job carries its company inline. Not an id to resolve, not a _links stub — the whole firmographic record, in the same response, on every row.

{
  "id": "greenhouse:4820193",
  "title": "Senior Data Engineer",
  "company": {
    "slug": "figma",
    "name": "Figma",
    "domain": "figma.com",
    "industry": "Software Development",
    "employee_count": 1400,
    "size_range": "1001-5000",
    "hq": { "country": "US", "region": "California", "locality": "San Francisco" },
    "funding": { "last_round_type": "Series E", "total_investment_usd": 748000000 }
  }
}

That's the point of the product. A job feed that gives you a company name means you still have to go and find out who that company is; one request here answers "remote Rust roles at Series-B-or-later companies with under 500 people" without a second call, because the answer was already in the payload.

There are ~158,545 companies with firmographic records behind those embeds.

Three shapes of company#

job.company is not one type. It's one of three, and code that assumes the first will throw on the second.

const isFull = (c) => Boolean(c?.slug);
 
// Safe against all three shapes.
const size = isFull(job.company) ? job.company.employee_count : null;

The PublicCompany record#

Country codes are inconsistent#

{
  "location": { "countries": ["United States"] },
  "company":  { "hq": { "country": "US" } }
}

data_tier has 10 values, not 3#

data_tier records where a firmographic record came from, which is a proxy for how complete it is. It's documented as three values in a quality order: remco > linkedin > free.

// Fragile — silently drops 7 live tiers.
const good = c.data_tier === "remco" || c.data_tier === "linkedin";
 
// Better — asks the real question.
const usable = c.employee_count != null && c.industry != null;

Firmographic filtering, three ways#

The firmographics are filterable server-side, from two directions — with the client-side embed pattern as the fallback for anything the filters don't cover.

1. Search companies directly#

/v1/companies is a real search now: q (name substring), industry, country (HQ — full name or ISO-2), size, employee_count_gte/lt, and has_jobs=true, with a total and offset paging. When the question is company-first — "which fintech companies in Germany are hiring?" — ask it directly:

curl -H "Authorization: Bearer $HYPERJOBS_KEY" \
  "https://api.hyperjobs.io/v1/companies?industry=Financial%20Services&country=DE&has_jobs=true"

Every result carries jobs_count, so "is hiring" and "how hard" arrive in the same payload.

2. Filter jobs on company attributes#

/v1/jobs grew a company axis: company_industry, company_size, employee_count_gte/lt, funding_gte/lt, company_country, and domain. When the question is job-first — "remote Rust roles at 50–500-person companies" — the firmographic predicate goes into the jobs query:

const qs = new URLSearchParams({
  skill: "rust",
  work_arrangement: "Remote", // exact and case-sensitive
  employee_count_gte: "50",
  employee_count_lt: "501", // exclusive bound
  limit: "200",
});
 
const { data, total } = await fetch(`https://api.hyperjobs.io/v1/jobs?${qs}`, {
  headers: { Authorization: `Bearer ${process.env.HYPERJOBS_KEY}` },
}).then((r) => r.json());

One request, and total counts exactly the set you asked for — the API applied the size predicate, so there's no page-the-world step to count matches. (An early draft of this API had no company axis here, which forced a client-side filter over embeds that total couldn't reflect; that whole workaround never shipped.)

3. Filter client-side over the embeds#

Still the route for fields with no server-side filter — founded_year, followers, stock, funding stage (only amounts are filterable). The firmographics arrived with every job, so local predicates cost nothing extra:

const matches = data.filter((job) => {
  const c = job.company;
  // No slug means the minimal fallback — founded_year doesn't exist on it, so
  // this company can't answer the question either way.
  if (!c?.slug) return false;
  return c.founded_year != null && c.founded_year >= 2020;
});

When to call the company endpoints#

• /v1/companies whenever the question is about companies rather than postings — name lookup (?q=), firmographic search, or building a directory. (An early draft made this a browse-only, top-200 endpoint; it isn't one.)
• /v1/companies/{slug} when you have a slug from somewhere else and want the record without a job attached. It matches on linkedin_slug and 404s on an unknown one — the only endpoint here that 404s on a bad value rather than returning empty.

When you just fetched a job, you rarely need either — the embed already carries the whole firmographic record. (jobs_count is the one field only the company endpoints add.)

Next#