Job Schema

A successful POST /v1/jobs/search returns { metadata, data }, where data is an array of normalized job objects. Every job follows the same shape regardless of source. Most fields are nullable - a source that doesn't supply a value yields null.

Metadata

Identity & links

IDs are per source. The same role posted to LinkedIn and to the company's Greenhouse board comes back as two records with two IDs, so do not use id to deduplicate across sources - measured cross-source duplication is about 1.3%.

company_object

Every field is independently optional. Coverage depends on how the company was resolved, so a job may carry a domain and a logo but no employee_count. The object itself is null rather than an object full of nulls when we know nothing beyond the name, so if (job.company_object) is a safe test.

sources

sources lists every source we have seen the posting on, not only the first, and is present on every job. source_url is unchanged: it still points at the source the job was first seen on, so existing integrations keep reading the same value.

Read the array rather than assuming its length. Postings are keyed per source today, so it normally holds a single entry.

Dates & lifecycle

verified_at advances on every recheck; last_seen_at advances only on the rechecks that found the posting still open. A verified_at newer than last_seen_at therefore means the most recent check did not confirm the job, which is an earlier signal than closed_at, set only once the posting is confirmed gone.

The timestamp formats differ by origin. last_seen_at, verified_at and closed_at are ours and are UTC, written YYYY-MM-DD HH:MM:SS. discovered_at and sources[].seen_at are ISO-8601 with an offset. date_posted is whatever the source publishes: most give a full ISO-8601 timestamp, some give a bare YYYY-MM-DD, so parse it as either rather than assuming a fixed shape.

Location

work_arrangement is the three-way form of the workplace question. The remote boolean reads false for hybrid and onsite alike, so it cannot separate them; work_arrangement can. hybrid is derived from work_arrangement, so the two always agree. Filter on it with work_arrangement_or. See field coverage for how much of the corpus carries it today.

Compensation

Pay is present only when the posting discloses it, which is roughly a quarter of postings; the fields are null otherwise. min_annual_salary and max_annual_salary are annualized to a yearly figure (hourly, daily, weekly and monthly rates are scaled up), while salary_string preserves the original text. The _usd fields are populated for USD postings; for other currencies they are null, since no exchange-rate conversion is applied.

Classification & content

employer_type reports "employer" for every posting today - the classifier that would separate staffing agencies and republishing job boards from direct employers has not run yet, so the employer_type_or and employer_type_not filters do not narrow anything either.

seniority maps our internal lead bucket to "director" to keep the vocabulary stable, which files staff and principal individual contributors under a value that reads as people management. is_manager is the field that tells them apart: a principal engineer with no reports is is_manager: false, an actual director is true, and null means we don't know.

Field coverage

Fill rates measured on a stratified sample of 2,153 production postings drawn from all ten sources. Stratified means every source is represented well enough to measure, not in its production proportion, so these are per-field fill rates rather than a prediction of what a given query returns.

country and countries were 72.0% and continents 0% before location resolution was reworked; the rest of the location fields are unchanged.

work_arrangement is not populated yet. It fills in as postings are re-ingested and backfilled, and hybrid, which is derived from it, fills in with it. Until then, use remote.

latitude, longitude and postal_code are passed through from the source payload, and no posting in the sample supplied them. LinkedIn, about half the corpus, publishes none of the three and no workplace type either - its public pages simply do not carry them, so those fields stay null for LinkedIn postings permanently. Indeed, about 40% of the corpus, does publish coordinates and postal codes, so these fields fill in for Indeed postings as re-ingestion reaches them.

Reserved for compatibility

The response shape is frozen, so a few fields stay in it that JobsPipe does not populate. They are always present and always empty:

Do not branch on these fields. They are documented so that a client generated from the schema knows not to expect data in them, not because they are pending.