Taxonomies

Fields with a fixed set of values use the enums below. The value lists come from the OpenAPI spec: this page renders them from shared data that a build check keeps in sync with the spec. Values are lowercase snake_case. Pass them to filters exactly as written.

Every enum field on a job can also be null, which means unknown. See Null semantics.

Seniority

seniority is inferred, mostly from the title. Filter with seniority_or.

seniority	Meaning
intern	Internship or working-student role.
junior	Entry level or early career.
mid	Experienced individual contributor.
senior	Senior individual contributor.
lead	Leads a team or a function, or a staff-level individual contributor. "Head of" titles land here.
director	Director of a department or function.
vp	Vice president.
c_level	C-suite executive, for example CEO, CTO or CFO.

Tip

Titles are messy. A “Head of Revenue Operations” at a 40-person startup and at a 10,000-person enterprise both map to lead. When the exact level matters, filter on title_or as well.

Employment type

employment_type is normalized from the posting. Filter with employment_type_or.

employment_type	Meaning
full_time	Permanent full-time role.
part_time	Permanent part-time role.
contract	Fixed-term contract or freelance engagement.
internship	Internship.
temporary	Temporary or seasonal role.

Techmap calls this field contractType (per its reference). See the Field dictionary.

Job family

job_family is inferred from the title and description. Filter with job_family_or.

In the v1 preview, job_family is a string, not a fixed enum. Values are lowercase snake_case. The values in the sample data are:

Value	Example titles (illustrative)
engineering	Senior Robotics Engineer, Data Engineer, Staff Platform Engineer
sales	Account Executive, VP of Sales
operations	Head of Revenue Operations, Warehouse Operations Intern
marketing	Product Marketing Manager
data	Clinical Data Analyst
customer_success	Customer Success Manager

Not a closed list yet

Other values can appear. Do not reject a job because its job_family is not in this table. To see which families a company hires for, read top_job_families on its company profile.

Providers use their own taxonomies. JobsPipe, for example, maps jobs to ISCO-08, ISIC and ESCO (per JobsPipe docs). BetterJobs returns its own job_family so one filter works across every source.

Status and closed reason

status is open or closed. When a job closes, closed_reason says why. While the job is open, closed_reason is null.

status	Meaning
open	The job is live. closed_reason is null.
closed	The job is no longer live. Hidden from search unless you set include_closed: true.

closed_reason	Meaning
filled	A source reports the position was filled.
expired	The posting reached its end date without a fill signal.
removed	The posting was taken down at its origin before it expired.
unknown	The job stopped appearing and no source gave a reason.

A closed job fires a job.closed event for watches that cover it. See Events and Freshness and lifecycle.

Waterfall strategy

waterfall.strategy decides which providers a search queries, and in what order. The default is cheapest_first.

strategy	What it does	Use when
cheapest_first	Starts with the BetterJobs index and adds providers only until the page is full.	Default. Good for most searches and for keeping cost low.
freshest_first	Tries the sources with the fastest refresh first.	You care about jobs posted in the last hours more than total coverage.
max_coverage	Queries every provider enabled on your plan.	Market sizing, backfills, or any time a missed job costs more than a credit.
consensus	Returns only jobs seen by at least min_sources sources (default 2).	You need high confidence the job is real, for example before outbound.
own_only	Uses the BetterJobs index only. No partner providers.	Free and Starter plans, or when you need the simplest licensing.

Pick one with Choose a strategy. How the waterfall runs is in Waterfall.

Other enums

Field	Values	Where
salary.period	year, month, hour	Job
salary.origin	declared, inferred	Job. declared = stated in the posting, inferred = estimated by a source.
hiring_pulse.direction	up, flat, down	Company profile
sources[].provider	betterjobs, reqbeat, signalsapi, theirstack, jobspipe, coresignal, techmap	Job, company profile. betterjobs is the BetterJobs index.
status (search)	queued, running, completed, partial, failed, on_hold	Async search. See Async searches.
status (provider)	operational, degraded, down	GET /v1/providers. See Provider status.