Enums & vocabularies

The complete vocabularies behind the enum filters on /v1/jobs. If a filter just returned a 400, the hint in the body names the values on this page.

curl "…/v1/jobs?seniority=Mid-Senior level"   # ✓ 198,375 jobs
curl "…/v1/jobs?seniority=mid-senior level"   # ✗ 400 — wrong case
curl "…/v1/jobs?seniority=Senior"             # ✗ 400 — not a value
curl "…/v1/jobs?seniority=5-10"               # ✗ 400 — that's experience_level

Counts below are from a recent snapshot. They're here to show you the shape of each distribution — don't hardcode them. For a live count of any value, send the filter with limit=1 and read total:

# The live number of Director-level jobs, without transferring any of them.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "seniority=Director" --data-urlencode "limit=1"
# → { "data": [ … ], "total": 26465, "limit": 1, "offset": 0 }

/v1/meta gives live totals for jobs, companies, the source breakdown, and per-field fill rates (coverage_pct) — but no per-enum counts for the vocabularies below.

Quick reference#

Comma = OR on every multi-value filter, with one exception: skill, where every listed value is required. That's the one inversion to keep straight — see below. country and company_country aren't enums but take a full name or an ISO-2 code, comma = OR — ?country=US,Germany works, and an unrecognised ISO-2 code is a 400.

seniority#

Six values. Filter: ?seniority=. Field: job.seniority.

Note the shape: Mid-Senior level is nearly half of everything classified, so it's a weak filter on its own. Management and Director are distinct values, not synonyms — a query for leadership roles needs both, which is one request: ?seniority=Director,Management (comma = OR).

experience_level#

Four bands, in years. Filter: ?experience_level=. Field: job.experience_level.

The values are literal strings — ?experience_level=5-10, not 5 and not 5–10 with an en-dash. There's no range syntax and no numeric comparison.

work_arrangement#

Three values. Filter: ?work_arrangement=. Field: job.work_arrangement.

On-site carries a hyphen and a lower-case s. Onsite, On-Site, and onsite all return zero rows.

continent#

Seven values. Filter: ?continent=, comma = OR. Field: job.location.continent.

Africa · Antarctica · Asia · Europe · North America · Oceania · South America

Title Case, with the space in the two-word names — North America, not north-america. A value outside the seven is a 400 naming the list.

employment_type#

Filter: ?employment_type=. Field: job.employment_type.

FULL_TIME dominates so heavily that the rest are a rounding error by comparison; for a current count of any one of them, send it with limit=1 and read total.

SCREAMING_SNAKE_CASE, always. Full-time, full_time, and FULLTIME all return zero rows.

It's an array, not a value#

A posting can carry several types at once, so the field holds a list — ["FULL_TIME","TEMPORARY"] for a full-time contract role, and 20+ combinations occur in the data. The filter matches a value inside that list, so ?employment_type=FULL_TIME finds both ["FULL_TIME"] and ["FULL_TIME","TEMPORARY"] — and ?employment_type=FULL_TIME,CONTRACTOR matches either type (comma = OR).

job.employment_type.includes("FULL_TIME");     // ✓ — just an array

education_requirements#

Filter: ?education= — note the parameter is education, not education_requirements, though the field it filters is job.education_requirements.

All lower-case, all with a space, none pluralised. Bachelor degree, bachelors degree, and Bachelor's are a 400 naming the five values. Comma = OR (overlap match): ?education=bachelor degree,postgraduate degree matches postings listing either.

Also an array field — a real array, not a raw JSON string — and also sparse: the five values together cover well under a third of the dataset, because most postings state no education requirement at all. A null means the posting was silent, not that no degree is required, so filtering on education excludes the large majority of jobs that simply didn't say.

taxonomies#

28 job families. Filter: ?taxonomies=. Field: job.taxonomies. Title Case, with spaced ampersands in the compound names.

Administrative · Agriculture · Art & Design · Construction · Consulting · Creative & Media · Customer Service & Support · Data & Analytics · Education · Energy · Engineering · Finance & Accounting · Healthcare · Hospitality · Human Resources · Legal · Logistics · Management & Leadership · Manufacturing · Marketing · Sales · Science & Research · Security & Safety · Social Services · Software · Technology · Trades · Transportation

Per-taxonomy counts aren't published anywhere. For the distribution, query each value with limit=1 and read total — 28 cheap requests, well within a minute's rate limit.

Present on about 64% of postings — a job with no taxonomy isn't uncategorisable, it just wasn't classified.

The & needs URL-encoding as %26, or the query string ends at the ampersand and the rest of your filters vanish:

# The shell and the URL both need to leave `&` alone. --data-urlencode does both.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "taxonomies=Finance & Accounting"

visa_sponsorship#

Two values. Filter: ?visa_sponsorship=. A single value, not a comma list.

Anything else — including true — is a 400.

language#

Filter: ?language=, comma = OR. Field: job.job_language.

The detected language of the posting. The field stores the short lower-case ISO-639-1 code — en is by far the most common — but the filter takes either the full name or the code: ?language=English and ?language=en are the same query.

33 codes are supported:

en · fr · de · nl · es · it · pt · pl · sv · zh · ja · hu · id · no · cs · el · da · fi · uk · ro · tr · bg · sk · ko · ru · hr · ar · vi · sl · sr · th · he · ms

Not a validated enum — a value outside the list matches nothing rather than erroring.

source#

64 public platform slugs return rows, documented in full on the sources page. There is no second tier: every platform we list is a value you can filter on. The filter takes the slug — lever, not the stored lever.co (the stored value is still accepted as input) — and comma = OR. exclude_source takes the same values to filter platforms out.

The keys of /v1/meta.sources are this list, live, with counts. It's the only vocabulary the API will enumerate for you — and worth reading, because source is a csv filter rather than an enum: an unknown value matches nothing instead of returning a 400.

source_type#

Comma = OR, and this one is a checked enum — a value off the list is a 400. It filters provenance, not duplication: cross-source mirrors are already folded, so source_type=ats selects employer-authored records rather than removing copies. The same value appears as source_type on every Job object.

skill#

An open vocabulary of canonical tokens, not an enum — far too many values to list, and it grows.

The trap is that displayed skills don't always round-trip: you see Machine Learning, but the filter wants machinelearning. A few aliases (c++→cpp, c#→csharp, .net→dotnet, node.js/nodejs→node, react.js→react, vue.js→vue, golang→go) are translated for you; multi-word names are not. See skills & taxonomies.

Commas mean OR — except skill#

Every multi-value filter treats a comma-separated list as OR:

curl "…/v1/jobs?taxonomies=Software,Healthcare"   # either family
curl "…/v1/jobs?employment_type=FULL_TIME,INTERN" # either type
curl "…/v1/jobs?seniority=Director,Management"    # leadership, one request

The one exception is skill, where comma = AND — every listed skill must be present, because "needs Python and AWS" is what a skill list means. For OR across skills, run one request per value and merge on id.

Shape parameters#

Two more closed vocabularies live on the shape side of the query string, and they're validated the same way:

• description_format — text | html. Omit the parameter and the response has no description key at all (smaller payloads).
• collapse — true | title,organization. Both name the same grouping; see duplicates & collapsing.

Any other value is a 400.

Validating before you send#

The server does this for you now: a bad enum value is a 400 whose hint lists the allowed values, so a client-side lookup table is a UX nicety rather than a correctness requirement. The one list still worth checking dynamically is source — it's a csv filter, not an enum (unknown values match nothing), and it's the one vocabulary that changes on its own:

const { sources } = await (
  await fetch("https://api.hyperjobs.io/v1/meta", { headers })
).json();
 
if (!(input in sources)) {
  throw new Error(`Unknown source: ${input}. Valid: ${Object.keys(sources).join(", ")}`);
}

Related#