# Fields and values

Every field of the job object, the change event, the expired item and the company object, with its type, whether it is always present, every value it can take, its provenance and a real example. Generated from the code.

**What this covers:** The job object; field_sources: every key and every value it can take; Every value list; Change events, expired and withdrawn items; The /v1/jobs page, embeddings and relevance; The company object; How this page stays correct.

**Assumed knowledge:** [Fields](./api-fields.md) for the reasoning behind absent, null and inferred.

**Canonical HTML:** https://jobopportunitiesapi.org/docs/api/fields-and-values  
**Machine-readable index:** https://jobopportunitiesapi.org/docs/ai/index.md  
**Last verified:** 2026-11-08  
**Superseded by:** the live API at https://api.jobopportunitiesapi.org and its spec at https://jobopportunitiesapi.org/openapi.json. Where this file and the API disagree, the API is right.

---

> **Generated, and checked on every build**: Field names, types and presence come from the Go structs the API serialises. Value lists come from the Go vocabularies, the database constraints and the data (closure reasons, categories), joined with every enum in the [OpenAPI document](https://api.jobopportunitiesapi.org/public/openapi.json). A test fails the build when the API has a field or a value this page does not list. Database values measured 2026-11-08.

- **always**: The key is on every object, with a value.
- **always, may be null**: The key is on every object; its value can be `null`. Check for null, not for absence.
- **omitted when empty**: The key is missing when there is no value. Never `null`.
- **only ...**: The key appears only in the case named (a parameter, an endpoint, a state).

---

<a id="fv-job"></a>

## 1. The job object

The same object on /v1/jobs, /v1/jobs/{id}, /v1/jobs/closed and every /v1/changes event, field for field. Replace your stored row with it; do not merge.

### 1.1 In depth

| Field | Type | Present | Values or format | field_sources key | Meaning | Example |
| --- | --- | --- | --- | --- | --- | --- |
| `relevance` | relevance object | only with sort=relevance, which this deployment does not offer today (it answers 422 sort_unavailable) |  |  | Ordering information for sort=relevance: score and tier. Ordering only, never comparable across queries. |  |
| `similarity` | number | only on /v1/jobs/similar |  |  | Cosine similarity of this job to the query vector of /v1/jobs/similar (-1 to 1, higher is closer, 4 decimals). Compare rows within one query only. |  |
| `id` | string | always | uuid |  | The job's identity. A uuid assigned once, when JOA first harvests the posting, and never changed or reused. Key your copy on it. | `"74e22048-ccb5-4dcd-903d-2ed00364e5e8"` |
| `slug` | string | always | lower-case words joined by hyphens |  | Readable alias: the title plus the first eight characters of the id. GET /v1/jobs/{id} accepts it, but key on id: the slug follows title corrections. | `"astronaut-candidate-74e22048"` |
| `title` | string | always |  |  | The job title as the source states it. | `"Astronaut Candidate"` |
| `company` | string | always |  |  | The employer's display name: the hiring organisation the posting names, or else the company JOA files it under. | `"Lyndon B. Johnson Space Center"` |
| `company_slug` | string | always |  |  | The company's readable key, as used by /v1/companies/{slug} and the company= filter. Not guaranteed stable across company-name corrections. | `"lyndon-b-johnson-space-center"` |
| `company_logo` | string | omitted when empty | absolute URL |  | URL of the company's logo, when JOA holds one. | `"https://logos.jobopportunitiesapi.org/joa-mono-gartnermarken-omsorg-pluss-hjemmebaserte-tjenester-i-fyllingsdalen-og-laksevag-b.png"` |
| `category` | string | omitted when empty | `Construction & Trades`, `Consulting & Strategy`, `Customer Support`, `Data & Analytics`, `Design`, `Education`, `Engineering`, `Finance`, `HR & Recruiting`, `Healthcare`, `Hospitality`, `Legal & Compliance`, `Logistics & Transport`, `Manufacturing`, `Marketing`, `Operations & Admin`, `Procurement`, `Product`, `Retail`, `Safety & Environment`, `Sales`, `Science & Research`, `Security`, `Skilled Technician` | `category` | The job family, read off the title by our classifier. Published only at confidence 0.6 or more. | `"Marketing"` |
| `category_confidence` | number | always, may be null | number from 0.6 to 1.0 |  | The classifier's confidence in category. Null when there is no category. | `0.65` |
| `country` | string | omitted when empty | two upper-case letters | `country` | Where the job is, as one ISO 3166-1 alpha-2 code. One code only: a role open in several countries carries one of them, or none when no single country applies; countries lists them all. | `"US"` |
| `countries` | array of strings | always | array of ISO 3166-1 alpha-2 codes |  | Every country the job is open to, country first when the job has one. [country] for a one-country job; a role open to several, such as Remote (United States / Canada), lists them all in the order the source names them. Always present: [] when no country is known. Match on it with country_match=any (added 8 Nov 2026). |  |
| `city` | string | omitted when empty |  | `location` | The city, when one could be established and verified. | `"Houston"` |
| `location` | string | omitted when empty |  | `location` | The free-text location as the posting states it. | `"Houston, Texas"` |
| `region` | string | omitted when empty | e.g. TX | `region` | State or province code where one could be established. US two-letter state codes today; omitted for most non-US rows. | `"TX"` |
| `remote` | string | omitted when empty | `remote`, `hybrid`, `on_site` | `remote` | Work arrangement. | `"remote"` |
| `remote_inferred` | boolean | always |  |  | true when remote is our reading of the location or title rather than a value the source stated. Always present, false included. Filter remote_confirmed=true for stated values only. | `true` |
| `employment_type` | string | omitted when empty | `Full-time`, `Part-time`, `Contract`, `Internship`, `Temporary` | `employment_type` | Employment type as the source states it, normalised to five values. | `"Temporary"` |
| `engagement` | array of strings | omitted when empty | `employee`, `vendor`, `other` | `engagement` | The working relationship. An array for adverts offering several (main option first, at most 3). | `["employee"]` |
| `engagement_confidence` | number | omitted when empty | number 0 to 1 |  | Measured precision of the rule that inferred engagement. Present only when field_sources.engagement is inferred. | `0.949999988079071` |
| `contract_category` | array of strings | omitted when empty | `permanent`, `fixed_term`, `project_based`, `seasonal`, `apprenticeship`, `internship`, `other` | `contract_category` | The contract kind. An array, main option first, at most 3. | `["permanent"]` |
| `contract_category_confidence` | number | omitted when empty | number 0 to 1 |  | Measured precision of the rule that inferred contract_category. Present only when inferred. |  |
| `agency` | string | omitted when empty | `direct`, `agency`, `umbrella` | `agency` | Whether the employer hires directly or through an agency or umbrella company. |  |
| `working_schedule` | string | omitted when empty | `full_time`, `part_time`, `flexible` | `working_schedule` | Full time, part time or flexible, as the posting establishes it. | `"full_time"` |
| `working_schedule_confidence` | number | omitted when empty | number 0 to 1 |  | Measured precision of the rule that inferred working_schedule. Present only when inferred. |  |
| `seniority` | string | omitted when empty | `Intern`, `Entry`, `Mid`, `Senior`, `Lead`, `Manager`, `Director`, `Executive` | `seniority` | Level read off the title by fixed keyword rules. Omitted when the title names no level. | `"Manager"` |
| `salary_min` | number | omitted when empty | number | `salary` | The lower (or only) figure, as stated, in salary_currency per salary_period. Never estimated. | `164395` |
| `salary_max` | number | omitted when empty | number | `salary_max` | The upper figure, as stated. Omitted for a single figure. | `164395` |
| `salary_currency` | string | omitted when empty | three upper-case letters, nearly always ISO 4217 (a few dozen live rows carry a code the source invented, such as YEN) | `salary_currency` | The currency of the figures. | `"USD"` |
| `salary_period` | string | omitted when empty | `hour`, `day`, `week`, `month`, `year` | `salary_period` | What the figures are per. For jobs in the United Kingdom, Ireland, the Netherlands and Denmark, a salary read from the advert page whose amount and period do not fit together (a monthly salary labelled per week, an hourly rate labelled per month) is withheld: the four salary fields are omitted. Where the advert states the unit next to the amount, that unit is used. A salary that reaches JOA another way (the source's own job feed, or our reading of the advert text) is not yet checked this way. | `"year"` |
| `salary_source` | string | omitted when empty | `structured`, `parsed_description` | `salary` | Where the figure came from. | `"structured"` |
| `salary_min_annual_eur` | number | omitted when empty | number, EUR per year |  | salary_min converted to an annual EUR figure at indicative rates, for comparison. Omitted when the period or currency is unknown: never guessed. | `151243.4` |
| `posted_at` | string | omitted when empty | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z | `posted_at` | When the source says the job was posted. The employer's own date; it can be days or weeks older than first_seen_at. | `"2026-11-07T17:58:05Z"` |
| `posted_at_precision` | string | omitted when empty | `date` |  | date when the source states a calendar date only: posted_at then carries that date at 12:00:00Z and its time means nothing. | `"date"` |
| `first_seen_at` | string | omitted when empty | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z |  | When this vacancy first entered JOA. On every row. | `"2026-11-07T21:09:52Z"` |
| `last_verified_at` | string | always | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z |  | The last time JOA positively confirmed the vacancy at its source (its own page, its ATS record, or a fresh read of the employer's job list); for a pushed role, the partner's last push. | `"2026-11-08T03:07:01Z"` |
| `last_verified_via` | string | always | `ats_api`, `first_harvest`, `partner_feed`, `posting_page`, `source_list`, `verifier`, `board_api` |  | Which kind of confirmation last_verified_at is. | `"source_list"` |
| `verification_stale` | boolean | present only when true |  |  | true when last_verified_at is older than 18 hours. A label, never a removal: the row stays served. | `true` |
| `status` | string | always | `live`, `closed` |  | live or closed. Always present, so a closed row is unambiguous. | `"live"` |
| `closed_at` | string | always, may be null | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z |  | When JOA recorded the closure. Null on a live row. | `"2026-11-08T04:55:48Z"` |
| `closed_reason` | string | always, may be null | `not_seen`, `expired_upstream`, `apply_link_dead`, `superseded_by_jobtech_loader`, `aggregator_host`, `generic_apply_url`, `portal_apply_url`, `employer_closed`, `deadline_passed`, `ai_verified_closed` |  | Why the row closed. Null on a live row. Parse it as an open set. | `"expired_upstream"` |
| `upstream_expired_at` | string | omitted when empty | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z |  | When our checks proved the vacancy dead, as opposed to closed_at, when we recorded the closure. | `"2026-11-08T04:42:57Z"` |
| `expires_at` | string | omitted when empty | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z | `expires_at` | When the vacancy stops being valid: the posting's own stated deadline, or the time we proved it dead. A past value on a live row is the source's claim. | `"2028-10-05T00:00:00Z"` |
| `apply_url` | string | omitted when empty | absolute URL |  | The employer's application page or ATS link. Use it as the apply button. It can change while the id stays the same. | `"https://www.usajobs.gov/job/891970300"` |
| `source_requisition_id` | string | omitted when empty |  | `source_requisition_id` | The identifier the source page states for the vacancy (its own requisition or posting reference), copied verbatim when the page publishes one. Not validated: occasionally it is a URL the page used as an identifier. JOA's own key for the posting is not published; id is the identity. | `"https://menke-gs.softgarden.io/#organization"` |
| `employer_website` | string | omitted when empty | absolute URL | `employer_website` | The employer's website as this posting states it. Different from the verified website on /v1/companies. | `"https://menke-gs.softgarden.io"` |
| `source` | string | always |  |  | The provider slug the row came from (see /v1/meta/providers). | `"usajobs"` |
| `source_type` | string | always | `ats`, `public_agency`, `career_site`, `aggregator`, `agency`, `unknown` | `source_type` | The kind of source, per row where classified, else the provider's class. | `"public_agency"` |
| `provider_type` | string | always | `direct`, `employer_ats`, `government`, `aggregator` |  | The provider's class in the older vocabulary, kept for compatibility. | `"government"` |
| `has_description` | boolean | always |  |  | true when JOA holds advert text for the row. | `true` |
| `description_length` | integer | always | integer, bytes | `description_length` | Length of the stored advert text. 0 means no text. | `11163` |
| `description_truncated` | boolean | always |  |  | true while JOA's stored copy is known to be cut short at its source and is being re-fetched. | `false` |
| `description` | string | only on request: /v1/jobs with include_description=true (limit 50 or fewer) and always on /v1/jobs/{id}, inside data (since 11 Nov 2026; the same value also sits beside data, kept for compatibility); never on /v1/changes events |  | `description` | The full advert text, with personal email addresses replaced by [personal contact removed]. Exception: on rows of source nhs_jobs it is the short summary the NHS Jobs feed publishes (about 150 characters, cut by NHS Jobs and ending in ...), followed by a Salary line, not the full advert; the full advert is at apply_url. | `"Summary\nAstronaut candidates will spend approximately two years training on the basic skills required to be an astronaut"` |
| `field_sources` | field_sources object | always |  |  | Per-field provenance: for each key, whether the value was published by the source, inferred by us, or absent. Every key on every row. |  |
| `canonical_url` | string | omitted when empty |  |  | The role's own page, for roles an employer pushed to JOA directly. Not set on crawled rows. |  |
| `attribution` | string | omitted when empty |  |  | Words the listing must be shown with: on roles an employer pushed directly, and on every row of a source whose licence requires it (for example NAV (arbeidsplassen.no), or NHS Jobs, whose rows contain public sector information under the Open Government Licence v3.0: keep the credit and the link to the advert and acknowledge the licence, see /terms). | `"NAV (arbeidsplassen.no)"` |
| `language` | string | always, may be null | two lower-case letters | `language` | ISO 639-1 code of the advert text, detected automatically. Null when not confident. | `"en"` |
| `language_confidence` | number | always, may be null | number 0 to 1 |  | The detector's score. Null with language. | `0.9491000175476074` |
| `language_basis` | string | always, may be null | `text`, `title+country`, `title`, `none` |  | What the detection read. | `"text"` |
| `country_confidence` | string | omitted when empty | `high`, `low` |  | Present only when we filled the country ourselves: high when two methods agree, low when a language model alone read the location text. |  |
| `compensation_type` | string | omitted when empty | `commission_only` | `compensation_type` | commission_only when the description says pay is entirely commission. Omitted otherwise; absence is not a claim of a base salary. | `"commission_only"` |
| `esco_occupation_uri` | string | omitted when empty | URI | `occupation` | ESCO occupation URI when the normalised title exactly equals one preferred ESCO label. Our inference, never the employer's. |  |
| `esco_occupation_label` | string | omitted when empty |  | `occupation` | The English preferred label of that ESCO occupation. |  |
| `isco_code` | string | omitted when empty | four digits | `occupation` | The 4-digit ISCO-08 unit group of that occupation. |  |
| `content_version` | string | always, may be null | opaque string, today 12 hex characters |  | The employer content version (9 Nov 2026). Changes only when the employer changed what the posting says: title, description (whitespace ignored), apply_url, employment_type, location text, a remote type or a salary the source states. Never changes when JOA re-derives or repairs a field (city, region, country, countries, category, seniority, company). Compare for equality only: a different value means refetch the row. Null for a row that has no version yet. |  |
| `content_changed_at` | string | always, may be null | ISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Z |  | When content_version last changed. For rows that existed on 9 Nov 2026 it starts at an older change clock that also moved on JOA's own repairs, so it can be later than the employer's last change, never earlier. Null exactly when content_version is. |  |
| `sponsor_registers` | sponsorRegisterList | always | array of objects, never null |  | The official government sponsor or work permit registers the employer appears on in the job's own country (10 Nov 2026): a register is shown only when its country is the job's country or one of the countries a multi-country role is open to, so a German job at an employer on the UK register reads []. One object per register: country, register, kind (licensed: the employer holds the licence or recognition the register lists, such as a UK sponsor licence or IND recognised sponsor status; filing_evidence: approved filings or permits such as US LCA or PERM, a Canadian positive LMIA or Irish employment permits), route, matched_name (as the register prints it), as_of (the register's own date), source_url, match_scope and statement (11 Nov 2026: exact_entity when the entry fits the employer named on the job; group_company when the name is the same but the employer's name carries another country or legal form, so a company with the same name is on the register and may not be the employer itself; also when the posting names another legal entity of the group, such as a Workday 'Company:' field, or when the entry is a site entity such as 'Standard Aero (San Antonio), Inc.' and the job is elsewhere; the statement always names the register entry). It means the employer appears on the official register as of that date, never that it will sponsor a visa for this job. Matched at employer level; a country is published only after a hand-checked sample reached 95% precision. [] when the employer is on none of the published registers, for a posting that names another employer than the company it was collected under, and (11 Nov 2026) for a posting whose employer is a franchisee or independently owned business, a staffing firm working at the company's site, or another employer that shares the company's name in another state. |  |
| `visa_checks` | visaCheckList | always; [] outside GB, IE, NL and DK, for a job not checked yet, or when switched off | array of one object, or [] |  | Visa information (11 Nov 2026) for a job in the United Kingdom, Ireland, the Netherlands or Denmark: one object with two factual checks of the advert against the official published rules of the country's main work route, each with its sources and dates. occupation_check says whether the occupation is on the official list of the route (status on_skilled_list, on_list_in_country_only, on_list_transitional_only, not_on_skilled_list, occupation_unknown, or not_assessed for the Netherlands, which has no list), with the occupation code used and how it was assigned. salary_check says how the advertised pay compares with the official thresholds (at_or_above_general_threshold, at_or_above_reduced_threshold_only, below_published_thresholds, salary_not_comparable with a reason), with the threshold, its currency and period. Both carry a plain statement, conditions an advert does not show, and sources (document, part, url, version). They describe facts and sources only: they are not advice and not a decision on any person's case, and they are the same for every reader. Computed daily from the advert title and the published salary; an occupation code is used only when the title exactly matches an ONS SOC 2020 coding index entry (UK, Ireland) or JOA's ISCO-08 code for the title (Denmark). Irish checks are shown only while JOA's daily check finds the DETE occupation lists unchanged. Pay is compared only when the job's own salary fields state it as hourly, monthly or yearly and it fits that period; otherwise the salary check is not comparable with reason pay_source_unverified (pay read from the page's structured data), pay_period_not_supported (weekly or daily pay) or pay_period_implausible (an amount that does not fit its period). No check (visa_checks []) for a recruitment agency advert (agency is set) or when the title names a country other than the job's country (English, Dutch, German and Danish country names). |  |
| `work_visa_text` | workVisaText | always | object: evidence_level, statements[], method_version, as_of, legal_note_code |  | What the advert itself says about visa sponsorship, work permits, relocation and the right to work. statements lists each statement found, with a code (text_permit_support, text_relocation_support, text_permit_required, text_no_sponsorship, text_citizenship_restriction), a quote copied word for word from the employer's advert in its own language (never translated or corrected), quote_lang and method published_by_employer. evidence_level follows a fixed rule: stated_closed when a statement closes the job (it wins), stated_open when a statement offers help with the visa or permit, no_information when the advert was read and is silent (the normal case, not a refusal), not_assessed when there is no current reading (not read yet, changed since, or a quote can no longer be shown exactly). It describes the advert: not advice and not a decision on any person's case. method_version and as_of name the reading. See /docs/api/work-visa-text for every value and the countries read. |  |
| `legal_note_code` | string | always, may be null | immigration_information, nhs_jobs_source or null |  | The code of the legal note that goes with this row (11 Nov 2026), null when none applies. Codes: immigration_information, on every job whose sponsor_registers or visa_checks is not empty or whose work_visa_text carries a statement, and nhs_jobs_source, on every job from NHS Jobs (source nhs_jobs). When both apply this key carries immigration_information (the first in order, so the value never changed for a row that had it) and legal_notes carries both. /v1/help lists every note (legal_notes) with its text, version and effective date. |  |
| `legal_note` | string | always, may be null | text or null |  | The text of that legal note, null exactly when legal_note_code is. For immigration_information: "This information is not immigration advice, legal advice or any other service to candidates. It is provided for information only and may be incomplete, inaccurate or out of date. Before starting any immigration or employment process, contact a qualified, certified professional." Immigration and sponsor information is information only, not immigration or legal advice. Show the legal_note with this information, unless you are an authorised immigration adviser presenting it within your regulated service. If you omit it, you take full responsibility. (Terms) |  |
| `legal_notes` | legalNoteRefs | always | array of {code, text}, never null |  | Every legal note that applies to this row (11 Nov 2026), in order (immigration_information first, then nhs_jobs_source), each as {code, text}; [] when none applies. legal_note_code and legal_note carry the first entry. For nhs_jobs_source the text is "These jobs come from NHS Jobs under the Open Government Licence v3.0. Review the Terms, section NHS Jobs: https://jobopportunitiesapi.org/terms#nhs-jobs". |  |
| `company_more_roles` | integer | only with collapse=company |  |  | With collapse=company: how many further roles of this employer the request read and folded behind this row (0 included). | `0` |
| `embedding` | embedding object | only with include=embedding (limit 100 or fewer) |  |  | The document vector for your own semantic search: model, dim, normalized, vector (or vector null with a reason). |  |

Parse every value list as an open set: a value added later is a compatible change. New keys can appear at any time too. Treat an unknown `closed_reason` as closed and an unknown `change` as stop showing the row.

**See also**

- [The job row](./api-fields.md#job-fields)
- [Nullability, in one table](./api-fields.md#nullability)
- [Every value list](./api-fields-and-values.md#fv-values)
- [Replace the whole row on every update](./recipes-local-copy.md#local-copy-replace)

<a id="fv-field-sources"></a>

## 2. field_sources: every key and every value it can take

One key per described field, on every job object, always present. Each key can take only the values listed.

### 2.1 In depth

| Key | Describes | Possible values | Example |
| --- | --- | --- | --- |
| `remote` | remote, remote_inferred | `published`, `inferred`, `absent` | `"inferred"` |
| `employment_type` | employment_type | `published`, `absent` | `"published"` |
| `category` | category, category_confidence | `inferred`, `absent` | `"absent"` |
| `seniority` | seniority | `inferred`, `absent` | `"absent"` |
| `salary` | the salary group (salary_min and salary_source) | `published`, `inferred`, `absent` | `"published"` |
| `salary_max` | salary_max | `published`, `inferred`, `absent` | `"published"` |
| `salary_currency` | salary_currency (inferred also when we filled an unstated unit) | `published`, `inferred`, `absent` | `"published"` |
| `salary_period` | salary_period (inferred also when we filled an unstated unit) | `published`, `inferred`, `absent` | `"published"` |
| `engagement` | engagement, engagement_confidence | `published`, `inferred`, `absent` | `"absent"` |
| `contract_category` | contract_category, contract_category_confidence | `published`, `inferred`, `absent` | `"absent"` |
| `agency` | agency | `published`, `inferred`, `absent` | `"absent"` |
| `working_schedule` | working_schedule, working_schedule_confidence | `published`, `inferred`, `absent` | `"absent"` |
| `location` | country, city, location: who decided the place | `published`, `inferred`, `absent` | `"inferred"` |
| `region` | region (published means we established one, partly by our own rules) | `published`, `absent` | `"published"` |
| `posted_at` | posted_at | `published`, `inferred`, `absent` | `"published"` |
| `description` | description, has_description | `published`, `absent` | `"published"` |
| `description_length` | description_length | `published`, `absent` | `"published"` |
| `source_type` | source_type | `published`, `inferred`, `absent` | `"inferred"` |
| `expires_at` | expires_at | `published`, `absent` | `"absent"` |
| `source_requisition_id` | source_requisition_id | `published`, `absent` | `"absent"` |
| `employer_website` | employer_website | `published`, `absent` | `"absent"` |
| `language` | language, language_confidence, language_basis | `detected`, `absent` | `"detected"` |
| `country` | country, country_confidence | `published`, `inferred`, `llm_inferred`, `unknown`, `absent` | `"published"` |
| `compensation_type` | compensation_type | `inferred`, `absent` | `"absent"` |
| `occupation` | esco_occupation_uri, esco_occupation_label, isco_code | `inferred`, `absent` | `"absent"` |

**See also**

- [field_sources](./api-fields.md#fieldsources-schema)
- [field_sources: per-field provenance](./ledger-provenance.md#field-sources)

<a id="fv-values"></a>

## 3. Every value list

Each closed field, with every value the API can return today and what it means. Closure reasons carry the number of closed rows a customer can receive with each.

### 3.1 In depth

**category** takes one of 24 job families: `Construction & Trades`, `Consulting & Strategy`, `Customer Support`, `Data & Analytics`, `Design`, `Education`, `Engineering`, `Finance`, `HR & Recruiting`, `Healthcare`, `Hospitality`, `Legal & Compliance`, `Logistics & Transport`, `Manufacturing`, `Marketing`, `Operations & Admin`, `Procurement`, `Product`, `Retail`, `Safety & Environment`, `Sales`, `Science & Research`, `Security`, `Skilled Technician`. The filter also accepts `uncategorised` for rows without one.

**salary_currency** is a three-letter code as the source states it, nearly always ISO 4217. On 2026-11-08 29 live rows carried a code that is not three upper-case letters or not ISO (such as `YEN`), so validate before converting.

**status**

_Source: api/openapi.yaml (Job.status), set by scanJob._
| Value | Meaning |
| --- | --- |
| `live` | Served now. |
| `closed` | Left its source or was closed; see closed_reason. |

**closed_reason (also on /v1/jobs/expired items)**

_Source: closed rows a customer can receive (ops/fields-db-snapshot.sh), partnerClosureReasons (api/partner.go), api/openapi.yaml._
| Value | Meaning | Closed rows |
| --- | --- | --- |
| `not_seen` | Stopped appearing at its source for the grace period. Usually a closure, occasionally a board that broke. | 7,767,747 |
| `expired_upstream` | Our checks proved the vacancy dead: two misses at least an hour apart, re-checked against the board or the job URL. | 896,511 |
| `apply_link_dead` | The posting's own apply link kept failing at its source (404 or 410, a closed-position page, the ATS reporting it closed, or a dead host) over at least 14 days. | 324,172 |
| `superseded_by_jobtech_loader` | A Swedish JobTech row replaced by the current loader on 2 Nov 2026. | 3,221 |
| `aggregator_host` | Closed by JOA on 16 Aug 2026 because the apply link led to a job aggregator, not the employer. | 3,029 |
| `generic_apply_url` | Closed by JOA because the apply link is a home page or one link shared by five or more different titles, not the job's own page. | 1,957 |
| `portal_apply_url` | Closed by JOA because the apply link is a public employment portal page instead of the employer's own. | 1,729 |
| `employer_closed` | A role the employer pushed to JOA: the employer closed it. | 0 today |
| `deadline_passed` | A role the employer pushed to JOA: its application deadline passed. | 0 today |
| `ai_verified_closed` | A review of the posting in a real browser found it closed. | 0 today |

**change (on /v1/changes events)**

_Source: CHECK listing_feed_kind_check, ledgerChange (api/handlers2.go)._
| Value | Meaning |
| --- | --- |
| `created` | The row entered the served set for the first time after your cursor. Insert it. |
| `updated` | A row that changed, or came back: a closed row that re-opened or a withdrawn row that was re-admitted. Replace your row by id. |
| `withdrawn` | JOA stopped serving the row (quality verdict, duplicate hold, opt-out). The job may still say status live: stop showing it anyway. |
| `delisted` | The vacancy closed. The job carries status closed, closed_at and closed_reason. Mark it closed. |

**status on an id-only event job**

_Source: ledgerChange (api/handlers2.go)._
| Value | Meaning |
| --- | --- |
| `withdrawn` | The row was withdrawn and may not be shown. |
| `closed` | The row was delisted. |

**remote**

_Source: CHECK listings_remote_type_check._
| Value | Meaning |
| --- | --- |
| `remote` | The posting says the job is done fully from home or from anywhere, with no regular office attendance. |
| `hybrid` | The posting offers or requires a mix of office and remote work, for example 'remote possible', 'telework 2 days a week' or partial remote. |
| `on_site` | The job is done at the employer's location; the posting excludes remote work, mentions it only as occasional, or the role is hands-on (care, warehouse, driving). |
| not stated (null) | The posting says nothing we can read about where the work is done. |

remote_inferred=true marks all of these as our reading of the text, not an employer field.

**employment_type**

_Source: CHECK listings_employment_type_check._
| Value | Meaning |
| --- | --- |
| `Full-time` | Full time. |
| `Part-time` | Part time. |
| `Contract` | Contract. |
| `Internship` | Internship. |
| `Temporary` | Temporary. |

**engagement (array)**

_Source: contractFilterVocab (api/contract.go), CHECK listings_engagement_values._
| Value | Meaning |
| --- | --- |
| `employee` | An employment relationship with an employer of record that runs payroll: the advertiser, a temp agency or an umbrella company. |
| `vendor` | A service relationship: the person invoices as self-employed or through their own company (freelance, contractor, B2B, US 1099). |
| `other` | A stated relationship that is clearly neither: hybrid civil-law forms and dependent-contractor arrangements. |

**contract_category (array)**

_Source: contractFilterVocab, CHECK listings_contract_category_values._
| Value | Meaning |
| --- | --- |
| `permanent` | Open-ended. |
| `fixed_term` | Fixed term. |
| `project_based` | For a project. |
| `seasonal` | Seasonal. |
| `apprenticeship` | Apprenticeship. |
| `internship` | Internship. |
| `other` | Another kind. |

**agency**

_Source: contractFilterVocab, CHECK listings_agency_values._
| Value | Meaning |
| --- | --- |
| `direct` | The employer hires directly. |
| `agency` | Through a staffing agency. |
| `umbrella` | Through an umbrella company (employed by it, usually understood as freelancing). |

**working_schedule**

_Source: contractFilterVocab, CHECK listings_working_schedule_values._
| Value | Meaning |
| --- | --- |
| `full_time` | Full time. |
| `part_time` | Part time. |
| `flexible` | Flexible hours. |

**seniority**

_Source: CHECK listings_seniority_check._
| Value | Meaning |
| --- | --- |
| `Intern` | Intern, trainee, apprentice. |
| `Entry` | Junior, graduate. |
| `Mid` | Mid level. |
| `Senior` | Senior. |
| `Lead` | Lead, principal, staff. |
| `Manager` | Manager, supervisor. |
| `Director` | Director, head of. |
| `Executive` | Chief, president, founder. |

**salary_period**

_Source: CHECK listing_extract_salary_period_canonical and the values live listings carry._
| Value | Meaning |
| --- | --- |
| `hour` | Per hour. |
| `day` | Per day. |
| `week` | Per week. |
| `month` | Per month. |
| `year` | Per year. |

**salary_source**

_Source: CHECK listings_salary_source_check_v2, minus the values jobCols hides with NULLIF._
| Value | Meaning |
| --- | --- |
| `structured` | A field the source published. |
| `parsed_description` | A figure the advert text states, read out by our rules. |

**source_type**

_Source: sourceTypeAlias (api/provenance.go), joa.providers.source_type._
| Value | Meaning |
| --- | --- |
| `ats` | An applicant tracking system. |
| `public_agency` | A public employment service. |
| `career_site` | The employer's own careers site. |
| `aggregator` | Reserved: matches no rows today. |
| `agency` | Reserved: matches no rows today. |
| `unknown` | The class is not recorded. |

**provider_type**

_Source: joa.providers.source_class of redistributable providers._
| Value | Meaning |
| --- | --- |
| `direct` | Careers site (career_site). |
| `employer_ats` | ATS (source_type ats). |
| `government` | Public agency (public_agency). |
| `aggregator` | Reserved. |

**last_verified_via**

_Source: joa.last_verified_via() over every input, lastVerifiedViaExpr (api/handlers.go)._
| Value | Meaning |
| --- | --- |
| `ats_api` | The posting's record in its ATS API. |
| `first_harvest` | Nothing newer than the harvest that brought it in. |
| `partner_feed` | The employer's last push or heartbeat. |
| `posting_page` | The posting's own page answered live. |
| `source_list` | A fresh read of the employer's own job list included it. |
| `verifier` | A check before 23 Oct 2026 whose method was not recorded. |
| `board_api` | Ashby's own job board listed it. |

**language_basis**

_Source: langBasis (api/handlers.go)._
| Value | Meaning |
| --- | --- |
| `text` | The advert text. |
| `title+country` | An English title in an English-speaking country; confidence capped at 0.85. |
| `title` | The title (the text was missing or too short). |
| `none` | No usable evidence. |

**posted_at_precision**

_Source: Job.PostedAtPrecision (api/handlers.go)._
| Value | Meaning |
| --- | --- |
| `date` | The source states a date, not a time. |

**country_confidence**

_Source: countryConfidence (api/provenance.go)._
| Value | Meaning |
| --- | --- |
| `high` | Two methods agree. |
| `low` | A language model alone read the location text. |

**compensation_type**

_Source: compensationTypeValues (api/jobfilter.go)._
| Value | Meaning |
| --- | --- |
| `commission_only` | Paid entirely by commission, no base salary. |

**field_sources values**

_Source: the src* constants (api/provenance.go)._
| Value | Meaning |
| --- | --- |
| `published` | The source stated it. |
| `detected` | language only: our detector's reading of the text. |
| `inferred` | We produced it from other text or by a rule. |
| `absent` | No value. |
| `llm_inferred` | country only: a language model alone read the location text. |
| `unknown` | country only: the row has a country but nothing records where it came from. |

**embedding.reason**

_Source: reason constants (api/vectors.go)._
| Value | Meaning |
| --- | --- |
| `no_vector` | The row has no vector yet. |
| `vectors_unavailable` | The vector service did not answer in time; repeat the call. |

**relevance.tier**

_Source: RelevanceInfo (api/handlers.go)._
| Value | Meaning |
| --- | --- |
| `exact` | Exact match. |
| `synonym` | Matched a synonym. |
| `abbreviation` | Matched an abbreviation. |
| `typo` | Matched despite a typo. |

**withdrawn_reason (on /v1/jobs/withdrawn items and the withdrawn answer of /v1/jobs/{id})**

_Source: withdrawnReasons (api/withdrawn.go), api/openapi.yaml WithdrawnReason._
| Value | Meaning |
| --- | --- |
| `employer` | The employer withdrew the role or opted out of JOA. |
| `duplicate` | A duplicate of another listing JOA serves. |
| `unverified` | JOA could not confirm it at its source recently; usually comes back once confirmed. |
| `apply_link` | Its apply link stopped working. |
| `quality` | It no longer meets a serving rule (for example the link leads to a job board or an agency). |
| `policy` | Its source may no longer be shown, or the row was removed. |
| `closed` | It has closed since it was withdrawn (it is in /v1/jobs/expired too). |
| `other` | In transition at the moment you asked. |
| `country_corrected` | We corrected the job's country, so it no longer belongs to the country you filter by; it may still be served under its new country. Listed only when you pass country or your key has a country lock, once, at the correction. |

**See also**

- [Closed roles](./ledger-data-model.md#closed-roles)
- [The four change kinds, and the one that breaks integrations](./endpoints-changes.md#change-kinds)
- [Contract: engagement, contract category, agency, working schedule](./api-parameters.md#params-contract)

<a id="fv-events"></a>

## 4. Change events, expired and withdrawn items

The /v1/changes event, the id-only job some events carry, the /v1/jobs/expired and /v1/jobs/withdrawn items with their envelopes, and the withdrawn answer of /v1/jobs/{id}.

### 4.1 In depth

**A /v1/changes event** (one per element of `data`).

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `change` | string | always | `created`, `updated`, `withdrawn`, `delisted` | What happened to the row after your cursor. | `"updated"` |
| `job` | job object | always |  | The complete job object, the same object /v1/jobs returns (without description). When the row may not be shown at all, only id and status (see the gone job). |  |
| `correction` | boolean | present only when true |  | true when the event was caused by JOA's own processing: a bulk correction of its data, or an `updated` of a job you already have whose change came from JOA and not from the employer. Not charged. | `true` |

**The job of an event whose row may not be shown at all** (an opt-out, or a source JOA may no longer redistribute): only these keys.

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string | always |  | The job id. All a copy needs to stop showing the row. |  |
| `status` | string | always | `withdrawn`, `closed` | closed when the row was delisted, withdrawn otherwise. |  |

**The /v1/changes page**

| Key | Meaning |
| --- | --- |
| `data` | The events, oldest first. |
| `next_since` | The cursor to send as `since` next time. Echoes your own cursor when there is nothing new. Opaque. |
| `count` | The number of events on this page. A page shorter than your limit means you are current. |

**A /v1/jobs/expired item.** Free: no records are charged for this feed.

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string | always |  | The id of a row that is closed now. | `"00198eff-ea49-4ba5-832a-98fa7cba6162"` |
| `closed_at` | string | always | ISO 8601 UTC timestamp with microseconds, e.g. 2026-11-08T04:55:48.123456Z | When JOA recorded the closure. Also the feed position. | `"2026-11-07T00:00:04.889337Z"` |
| `closed_reason` | string | omitted when empty | `not_seen`, `expired_upstream`, `apply_link_dead`, `superseded_by_jobtech_loader`, `aggregator_host`, `generic_apply_url`, `portal_apply_url`, `employer_closed`, `deadline_passed`, `ai_verified_closed` | Why it closed. | `"not_seen"` |

| Key | Meaning |
| --- | --- |
| `data` | Rows that are closed now, oldest closure first. A row that re-opened is no longer listed. |
| `count` | Items on this page. |
| `next_since` | The cursor for the next call. Opaque. |

**A /v1/jobs/withdrawn item.** Free: no records are charged for this feed.

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string | always |  | The id of a row that left the served set without closing and is still out. |  |
| `withdrawn_at` | string | always | ISO 8601 UTC timestamp | When it left the served set. Also the feed position. |  |
| `withdrawn_reason` | string | always | `employer`, `duplicate`, `unverified`, `apply_link`, `quality`, `policy`, `closed`, `other`, `country_corrected` | A coarse public reason category. |  |

| Key | Meaning |
| --- | --- |
| `data` | Rows that left the served set without closing and are still out, oldest first. A row that comes back is no longer listed. |
| `count` | Items on this page. |
| `next_since` | The cursor for the next call. Opaque. |

**GET /v1/jobs/{id} for a withdrawn row** answers `{"data": <this object>}` instead of a job. Free.

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | string | always |  | The job id you asked for. |  |
| `status` | string | always |  | Always withdrawn: the row was served and no longer is, without closing. |  |
| `withdrawn_at` | string | always | ISO 8601 UTC timestamp | When it left the served set. |  |
| `withdrawn_reason` | string | always | `employer`, `duplicate`, `unverified`, `apply_link`, `quality`, `policy`, `closed`, `other`, `country_corrected` | A coarse public reason category. |  |

**See also**

- [The four change kinds, and the one that breaks integrations](./endpoints-changes.md#change-kinds)
- [GET /v1/jobs/expired](./endpoints-jobs.md#endpoint-jobs-expired)
- [GET /v1/jobs/withdrawn](./endpoints-jobs.md#endpoint-jobs-withdrawn)
- [Closures and re-openings](./recipes-local-copy.md#local-copy-closures)

<a id="fv-page"></a>

## 5. The /v1/jobs page, embeddings and relevance

The envelope around job rows, the embedding object of include=embedding, and the relevance object.

### 5.1 In depth

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `data` | array of job objects | always, may be null |  | The job objects of this page. |  |
| `next_cursor` | string | always, may be null |  | Opaque cursor for the next page; null on the last page. Store it as a string, never parse it. |  |
| `has_more` | boolean | always |  | true when another page exists. |  |
| `paging` | string | omitted when empty |  | Keyless surface only: why no cursor is offered. |  |
| `note` | string | omitted when empty |  | Keyless surface only: a human-readable note about paging. |  |
| `total_estimate` | integer | omitted when empty |  | With include_total=true: how many rows match the filters, exact up to 10,000 (10001 reads as more than 10,000). Not charged. |  |
| `total_estimate_status` | string | omitted when empty |  | exact, at_least or timed_out. |  |
| `location_ambiguous` | boolean | omitted when empty |  | With city=: true when the matched rows span more than one country. |  |
| `location_countries` | array | omitted when empty |  | With city=: the matched set's country breakdown. |  |
| `completeness` | object | omitted when empty |  | With require_fields=: how complete the page is for the fields you required. |  |
| `next_since` | string | omitted when empty |  | Only when the request carried since (9 Nov 2026): the token to send as since on your next poll, the same on every page of one walk. Opaque: store it as a string and send it back unchanged. |  |
| `hints` | []searchHint | omitted when empty |  | Only on an empty first page of a live keyed search (12 Nov 2026): why nothing matched, one finding per item with param, value, reason, live_jobs and text. Each says only what one quick check found; a check that fails or is late is left out. |  |

**embedding** (with `include=embedding`)

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `model` | string | always |  | The embedding model, Qwen/Qwen3-Embedding-8B. | `"Qwen/Qwen3-Embedding-8B"` |
| `dim` | integer | always |  | Vector length, 1024. | `1024` |
| `normalized` | boolean | always |  | true: unit length, so cosine similarity equals the dot product. | `true` |
| `vector` | array of numbers | always, may be null | 1024 float32 values | The vector, or null when the row has none yet. |  |
| `reason` | string | omitted when empty | `no_vector`, `vectors_unavailable` | Why vector is null. | `"no_vector"` |

**relevance** (with `sort=relevance`, not offered on this deployment today)

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `score` | integer | always |  | Ordering score within one response only. |  |
| `tier` | string | omitted when empty | `exact`, `synonym`, `abbreviation`, `typo` | How the query matched. |  |

**See also**

- [How paging works](./api-pagination.md#cursor-basics)
- [How many rows match: include_total](./api-pagination.md#include-total)
- [Embeddings: include=embedding](./endpoints-jobs.md#job-embeddings)

<a id="fv-company"></a>

## 6. The company object

Every field of a /v1/companies row, and the closure history on a single company.

### 6.1 In depth

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `slug` | string | always |  | The company's readable key. | `"h-r-block"` |
| `name` | string | always |  | Display name. | `"H&R Block"` |
| `website` | string | omitted when empty |  | The company's domain, published only after we fetched it and found the company's name on it. |  |
| `website_verified` | string | omitted when empty | YYYY-MM-DD | The date that check last passed. |  |
| `logo` | string | omitted when empty |  | Logo URL. |  |
| `country` | string | omitted when empty | ISO 3166-1 alpha-2 | Headquarters country. | `"US"` |
| `industry` | string | omitted when empty |  | Industry label, published at confidence 0.6 or more. | `"Retail"` |
| `org_type` | string | omitted when empty |  | Organisation type label, published at confidence 0.6 or more. | `"Enterprise"` |
| `sectors` | array of strings | always, never null (empty array when none) |  | The job categories the company hires in most. | `["Finance","Customer Support","Operations & Admin"]` |
| `open_roles` | integer | always |  | Roles retrievable from this API now. | `19729` |
| `own_site_roles` | integer | always |  | Vacancies seen on the company's own careers page under a source JOA does not redistribute. Evidence of hiring, not inventory. | `0` |
| `careers_url` | string | omitted when empty |  | The company's careers page. |  |
| `source_types` | array of strings | always, never null (empty array when none) |  | The source types its roles come from. | `["career_site","ats"]` |
| `first_seen` | string | omitted when empty | YYYY-MM-DD | When the company first appeared. | `"2026-08-02"` |
| `closure_history` | array of closure objects | omitted when empty |  | Recent closed roles, on GET /v1/companies/{slug} only. |  |
| `seo_indexable` | boolean | only on the keyless website read, never on /v1 |  | Website use only: whether the public company page asks search engines to index it. |  |
| `seo_closed_180d` | integer | only on the keyless website read, never on /v1 |  | Website use only: closures in 180 days, an input of seo_indexable. |  |
| `seo_last_change` | string | only on the keyless website read, never on /v1 |  | Website use only: an input of seo_indexable. |  |

**closure_history items** (GET /v1/companies/{slug} only)

| Field | Type | Present | Values or format | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `slug` | string | always |  | The closed job's slug. |  |
| `title` | string | always |  | The closed job's title. |  |
| `closed_at` | string | always |  | When it closed. |  |
| `closed_reason` | string | always, may be null | `not_seen`, `expired_upstream`, `apply_link_dead`, `superseded_by_jobtech_loader`, `aggregator_host`, `generic_apply_url`, `portal_apply_url`, `employer_closed`, `deadline_passed`, `ai_verified_closed` | Why it closed. |  |

**See also**

- [The company row](./api-fields.md#company-fields)
- [GET /v1/companies](./endpoints-companies.md#endpoint-companies)

<a id="fv-generated"></a>

## 7. How this page stays correct

A generator reads the code and the database; a test refuses a build in which the API has something this page lacks.

### 7.1 In depth

1. `web/scripts/gen-fields-catalog.mjs` reads the Go structs (field names, JSON types, presence), the value lists enforced in Go, every enum in `api/openapi.yaml`, the database snapshot and the example rows, and writes `web/src/docs/fields-source.generated.ts`.
2. `ops/fields-db-snapshot.sh` reads the CHECK constraints, the category vocabulary, the provider classes, the `last_verified_via` function and the closure reasons customers can receive, from the replica.
3. `web/test/fieldsCatalog.test.mjs` re-runs the generator in check mode, and fails when a field or a value has no meaning written, or when the spec lists a property this page does not.
4. `api/fields_catalog_test.go` compares the field list with the compiled Go types by reflection, so a field cannot hide from the parser.

---

## Where to go next

This file is part of **API**. Others in the same group:

- [API overview](./api-overview.md): Hosts, versioning, caching, CORS and the HTTP conventions every endpoint follows. Read the hosts section first: getting it wrong costs people hours.
- [Authentication](./api-authentication.md): One header, three accepted spellings, and a deliberate refusal to tell an attacker which kind of wrong a wrong key is.
- [Keyless access](./api-keyless.md): What /public/* gives you with no account: real aggregate numbers against the live ledger (coverage, facets, freshness, providers, the price list, the spec). Job and company ROWS are not part of that anymore: they need a free key, full stop.
- [Rate limits](./api-rate-limits.md): Two independent ceilings (requests per minute and per day) plus a monthly record allowance that is a licence rather than a throttle. They fail differently.
- [Pagination](./api-pagination.md): Keyset cursors, not offsets. One rule matters more than the rest: hand next_cursor back exactly as you received it.

Always useful:

- [index.md](./index.md): the map of every file here
- [BUILD-A-SITE.md](./BUILD-A-SITE.md): the paste-whole brief for building against this API
- [quickstart.md](./quickstart.md): zero to a first authenticated response
- [api-errors.md](./api-errors.md): every status code and whether to retry it
