Job Schema

POST /v1/jobs/search returns { metadata, data }, where data is an array of job objects. Every job has the same shape whatever its source. Most fields are null when the source does not supply them.

Metadata

Identity & links

id is the posting's ID on its source, so its format varies (a number, a UUID, a hex string). Treat it as an opaque string.

A role listed on two boards is returned as one record, attributed to one source. Look it up by that source's ID; the other board's ID returns nothing.

company_object

Every field can be null on its own, so a job may carry a domain and a logo but no employee_count. The object is null when nothing beyond the name is known, so if (job.company_object) is a safe test.

company_object.intelligence

The employer as a business: revenue, type of organisation and legal identity. It is resolved in the posting's country, so the same name in two countries can carry two different records.

revenue_confidence tells you how far to trust revenue_usd, strongest first:

"intelligence": {
  "revenue_usd": 12500000,
  "revenue_year": 2025,
  "revenue_source": null,
  "revenue_confidence": "filed",
  "entity_kind": "company",
  "founded_year": 1998,
  "headcount": 140,
  "industry": "Software publishing",
  "hq_region": "California",
  "hq_city": "South San Francisco",
  "revenue_low_usd": null,
  "revenue_high_usd": null,
  "headcount_low": null,
  "headcount_high": null,
  "lei": "5493001KJTIIGC8Y1R12",
  "legal_name": "EXAMPLE SOFTWARE INC.",
  "group_lei": "213800ABCDEFGHIJKL12",
  "group_name": "EXAMPLE HOLDINGS PLC"
}

intelligence is null when there is no record for the company in that country. Inside it, every field is null when unknown: a company with no disclosed revenue still carries its entity_kind and lei, and a company known only by its legal entity still has an intelligence object.

The legal-entity fields are null when:

• lei and legal_name: we have not identified the company's legal entity in the posting's country.
• group_lei and group_name: the company has no recorded parent, or lei is null. A company that heads its own group can carry its own LEI as group_lei.

To search by LEI, including every company of a group, use lei_or.

sources

sources is present on every job and normally holds one entry. Read it as an array, but do not expect it to list every board a role appears on. source_url matches sources[0].url.

Dates & lifecycle

To tell whether a posting is still open, read status and closed_at. Don't compare verified_at with last_seen_at: on an open posting they describe the same check and can differ by minutes to hours, and a check that fails to reach the source is not recorded at all.

Timestamp formats differ. last_seen_at, verified_at and closed_at are UTC YYYY-MM-DD HH:MM:SS. discovered_at and sources[].seen_at are ISO-8601 with an offset. date_posted is as the source publishes it, usually ISO-8601 but sometimes a bare YYYY-MM-DD, so accept both.

Location

remote reads false for hybrid and onsite alike; work_arrangement separates them, and hybrid always agrees with it. Filter with work_arrangement_or. See field coverage.

Compensation

Pay is present only when the posting discloses it (roughly a quarter of postings). min_annual_salary and max_annual_salary are annualized (hourly, daily, weekly and monthly rates are scaled to a year); salary_string keeps the original text. The _usd fields convert other currencies at a fixed snapshot of European Central Bank rates, so treat them as approximate. They are null when the currency has no rate.

The estimated_* fields are a benchmark, not the employer's pay: percentiles of annual USD pay for the job's occupation and location, from public salary statistics or from pay posted for the same occupation in that country. They never replace observed pay; salary_type says which a job carries. The min_salary_usd filter uses observed pay only.

Classification & content

employer_type is classified per company. A company not yet classified is returned as "employer". See employer type.

seniority: "director" also covers lead, staff and principal individual contributors. Use is_manager to tell them apart: a principal engineer with no reports is false, an actual director is true, and null means unknown.

language is the language the posting is written in, not the language of its country. Filter with language_or / language_not.

technologies

Opt-in: send include_technologies: true on POST /v1/jobs/search and every job carries this list; without it the field is absent. Each returned job that names at least one technology costs 1 extra credit, once per job per calendar month. See billing for technologies.

Hiring signals

ghost_score is built from repost cadence, how long the posting has been up, and its content: 0 reads as a live vacancy, 100 as almost certainly not one. The max_ghost_score filter lets unscored jobs pass.

Field coverage

For a live figure on the fields a search filters on, read metadata.field_coverage in the response (see unknown values & coverage).

The table below is a sample of 500 recent postings (September 2026) from a broad query. Coverage varies by source, so a query narrowed to one source can differ a lot.

latitude and longitude come either from the source (coordinates_source: "source") or from the centre of the posting's city ("city_centroid"), which may be many kilometres from the workplace. No centroid is set for a country, a state, a metro area or Remote, or for the city-states (Singapore, Hong Kong, Macau).

Reserved for compatibility

These fields are always present and always empty:

Do not branch on them.

Data attributions

Some derived fields use public datasets:

• esco_skills uses the ESCO classification (© European Union, CC BY 4.0).
• seniority_source: "onet_prior" levels derive from the O*NET database by the U.S. Department of Labor, Employment and Training Administration (CC BY 4.0).
• estimated_*_annual_salary_usd benchmarks derive from U.S. Bureau of Labor Statistics OEWS data and metro_code from U.S. Census Bureau CBSA delineations (both public domain).
• City-centre coordinates (coordinates_source: "city_centroid") use the GeoNames geographical database (CC BY 4.0).