Job Opportunities API

Check the data. Then trust it.

api

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.

Last verified 2026-11-08 · Assumes: Fields for the reasoning behind absent, null and inferred. · Markdown copy

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).

1The 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.

In depthWhy it exists, what it is not, what people get wrong
FieldTypePresentValues or formatfield_sources keyMeaningExample
relevancerelevance objectonly 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.
similaritynumberonly on /v1/jobs/similarCosine 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.
idstringalwaysuuidThe 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"
slugstringalwayslower-case words joined by hyphensReadable 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"
titlestringalwaysThe job title as the source states it."Astronaut Candidate"
companystringalwaysThe employer's display name: the hiring organisation the posting names, or else the company JOA files it under."Lyndon B. Johnson Space Center"
company_slugstringalwaysThe 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_logostringomitted when emptyabsolute URLURL 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"
categorystringomitted when emptyConstruction & 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 TechniciancategoryThe job family, read off the title by our classifier. Published only at confidence 0.6 or more."Marketing"
category_confidencenumberalways, may be nullnumber from 0.6 to 1.0The classifier's confidence in category. Null when there is no category.0.65
countrystringomitted when emptytwo upper-case letterscountryWhere 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"
countriesarray of stringsalwaysarray of ISO 3166-1 alpha-2 codesEvery 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).
citystringomitted when emptylocationThe city, when one could be established and verified."Houston"
locationstringomitted when emptylocationThe free-text location as the posting states it."Houston, Texas"
regionstringomitted when emptye.g. TXregionState or province code where one could be established. US two-letter state codes today; omitted for most non-US rows."TX"
remotestringomitted when emptyremote, hybrid, on_siteremoteWork arrangement."remote"
remote_inferredbooleanalwaystrue 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_typestringomitted when emptyFull-time, Part-time, Contract, Internship, Temporaryemployment_typeEmployment type as the source states it, normalised to five values."Temporary"
engagementarray of stringsomitted when emptyemployee, vendor, otherengagementThe working relationship. An array for adverts offering several (main option first, at most 3).["employee"]
engagement_confidencenumberomitted when emptynumber 0 to 1Measured precision of the rule that inferred engagement. Present only when field_sources.engagement is inferred.0.949999988079071
contract_categoryarray of stringsomitted when emptypermanent, fixed_term, project_based, seasonal, apprenticeship, internship, othercontract_categoryThe contract kind. An array, main option first, at most 3.["permanent"]
contract_category_confidencenumberomitted when emptynumber 0 to 1Measured precision of the rule that inferred contract_category. Present only when inferred.
agencystringomitted when emptydirect, agency, umbrellaagencyWhether the employer hires directly or through an agency or umbrella company.
working_schedulestringomitted when emptyfull_time, part_time, flexibleworking_scheduleFull time, part time or flexible, as the posting establishes it."full_time"
working_schedule_confidencenumberomitted when emptynumber 0 to 1Measured precision of the rule that inferred working_schedule. Present only when inferred.
senioritystringomitted when emptyIntern, Entry, Mid, Senior, Lead, Manager, Director, ExecutiveseniorityLevel read off the title by fixed keyword rules. Omitted when the title names no level."Manager"
salary_minnumberomitted when emptynumbersalaryThe lower (or only) figure, as stated, in salary_currency per salary_period. Never estimated.164395
salary_maxnumberomitted when emptynumbersalary_maxThe upper figure, as stated. Omitted for a single figure.164395
salary_currencystringomitted when emptythree upper-case letters, nearly always ISO 4217 (a few dozen live rows carry a code the source invented, such as YEN)salary_currencyThe currency of the figures."USD"
salary_periodstringomitted when emptyhour, day, week, month, yearsalary_periodWhat 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_sourcestringomitted when emptystructured, parsed_descriptionsalaryWhere the figure came from."structured"
salary_min_annual_eurnumberomitted when emptynumber, EUR per yearsalary_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_atstringomitted when emptyISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Zposted_atWhen 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_precisionstringomitted when emptydatedate 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_atstringomitted when emptyISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05ZWhen this vacancy first entered JOA. On every row."2026-11-07T21:09:52Z"
last_verified_atstringalwaysISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05ZThe 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_viastringalwaysats_api, first_harvest, partner_feed, posting_page, source_list, verifier, board_apiWhich kind of confirmation last_verified_at is."source_list"
verification_stalebooleanpresent only when truetrue when last_verified_at is older than 18 hours. A label, never a removal: the row stays served.true
statusstringalwayslive, closedlive or closed. Always present, so a closed row is unambiguous."live"
closed_atstringalways, may be nullISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05ZWhen JOA recorded the closure. Null on a live row."2026-11-08T04:55:48Z"
closed_reasonstringalways, may be nullnot_seen, expired_upstream, apply_link_dead, superseded_by_jobtech_loader, aggregator_host, generic_apply_url, portal_apply_url, employer_closed, deadline_passed, ai_verified_closedWhy the row closed. Null on a live row. Parse it as an open set."expired_upstream"
upstream_expired_atstringomitted when emptyISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05ZWhen our checks proved the vacancy dead, as opposed to closed_at, when we recorded the closure."2026-11-08T04:42:57Z"
expires_atstringomitted when emptyISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05Zexpires_atWhen 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_urlstringomitted when emptyabsolute URLThe 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_idstringomitted when emptysource_requisition_idThe 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_websitestringomitted when emptyabsolute URLemployer_websiteThe employer's website as this posting states it. Different from the verified website on /v1/companies."https://menke-gs.softgarden.io"
sourcestringalwaysThe provider slug the row came from (see /v1/meta/providers)."usajobs"
source_typestringalwaysats, public_agency, career_site, aggregator, agency, unknownsource_typeThe kind of source, per row where classified, else the provider's class."public_agency"
provider_typestringalwaysdirect, employer_ats, government, aggregatorThe provider's class in the older vocabulary, kept for compatibility."government"
has_descriptionbooleanalwaystrue when JOA holds advert text for the row.true
description_lengthintegeralwaysinteger, bytesdescription_lengthLength of the stored advert text. 0 means no text.11163
description_truncatedbooleanalwaystrue while JOA's stored copy is known to be cut short at its source and is being re-fetched.false
descriptionstringonly 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 eventsdescriptionThe 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_sourcesfield_sources objectalwaysPer-field provenance: for each key, whether the value was published by the source, inferred by us, or absent. Every key on every row.
canonical_urlstringomitted when emptyThe role's own page, for roles an employer pushed to JOA directly. Not set on crawled rows.
attributionstringomitted when emptyWords 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)"
languagestringalways, may be nulltwo lower-case letterslanguageISO 639-1 code of the advert text, detected automatically. Null when not confident."en"
language_confidencenumberalways, may be nullnumber 0 to 1The detector's score. Null with language.0.9491000175476074
language_basisstringalways, may be nulltext, title+country, title, noneWhat the detection read."text"
country_confidencestringomitted when emptyhigh, lowPresent only when we filled the country ourselves: high when two methods agree, low when a language model alone read the location text.
compensation_typestringomitted when emptycommission_onlycompensation_typecommission_only when the description says pay is entirely commission. Omitted otherwise; absence is not a claim of a base salary."commission_only"
esco_occupation_uristringomitted when emptyURIoccupationESCO occupation URI when the normalised title exactly equals one preferred ESCO label. Our inference, never the employer's.
esco_occupation_labelstringomitted when emptyoccupationThe English preferred label of that ESCO occupation.
isco_codestringomitted when emptyfour digitsoccupationThe 4-digit ISCO-08 unit group of that occupation.
content_versionstringalways, may be nullopaque string, today 12 hex charactersThe 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_atstringalways, may be nullISO 8601 UTC timestamp, second precision, e.g. 2026-11-07T17:58:05ZWhen 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_registerssponsorRegisterListalwaysarray of objects, never nullThe 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_checksvisaCheckListalways; [] outside GB, IE, NL and DK, for a job not checked yet, or when switched offarray 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_textworkVisaTextalwaysobject: evidence_level, statements[], method_version, as_of, legal_note_codeWhat 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_codestringalways, may be nullimmigration_information, nhs_jobs_source or nullThe 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_notestringalways, may be nulltext or nullThe 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_noteslegalNoteRefsalwaysarray of {code, text}, never nullEvery 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_rolesintegeronly with collapse=companyWith collapse=company: how many further roles of this employer the request read and folded behind this row (0 included).0
embeddingembedding objectonly 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.

2field_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.

In depthWhy it exists, what it is not, what people get wrong
KeyDescribesPossible valuesExample
remoteremote, remote_inferredpublished, inferred, absent"inferred"
employment_typeemployment_typepublished, absent"published"
categorycategory, category_confidenceinferred, absent"absent"
seniorityseniorityinferred, absent"absent"
salarythe salary group (salary_min and salary_source)published, inferred, absent"published"
salary_maxsalary_maxpublished, inferred, absent"published"
salary_currencysalary_currency (inferred also when we filled an unstated unit)published, inferred, absent"published"
salary_periodsalary_period (inferred also when we filled an unstated unit)published, inferred, absent"published"
engagementengagement, engagement_confidencepublished, inferred, absent"absent"
contract_categorycontract_category, contract_category_confidencepublished, inferred, absent"absent"
agencyagencypublished, inferred, absent"absent"
working_scheduleworking_schedule, working_schedule_confidencepublished, inferred, absent"absent"
locationcountry, city, location: who decided the placepublished, inferred, absent"inferred"
regionregion (published means we established one, partly by our own rules)published, absent"published"
posted_atposted_atpublished, inferred, absent"published"
descriptiondescription, has_descriptionpublished, absent"published"
description_lengthdescription_lengthpublished, absent"published"
source_typesource_typepublished, inferred, absent"inferred"
expires_atexpires_atpublished, absent"absent"
source_requisition_idsource_requisition_idpublished, absent"absent"
employer_websiteemployer_websitepublished, absent"absent"
languagelanguage, language_confidence, language_basisdetected, absent"detected"
countrycountry, country_confidencepublished, inferred, llm_inferred, unknown, absent"published"
compensation_typecompensation_typeinferred, absent"absent"
occupationesco_occupation_uri, esco_occupation_label, isco_codeinferred, absent"absent"

3Every 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.

In depthWhy it exists, what it is not, what people get wrong

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.
ValueMeaning
liveServed now.
closedLeft 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.
ValueMeaningClosed rows
not_seenStopped appearing at its source for the grace period. Usually a closure, occasionally a board that broke.7,767,747
expired_upstreamOur 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_deadThe 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_loaderA Swedish JobTech row replaced by the current loader on 2 Nov 2026.3,221
aggregator_hostClosed by JOA on 16 Aug 2026 because the apply link led to a job aggregator, not the employer.3,029
generic_apply_urlClosed 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_urlClosed by JOA because the apply link is a public employment portal page instead of the employer's own.1,729
employer_closedA role the employer pushed to JOA: the employer closed it.0 today
deadline_passedA role the employer pushed to JOA: its application deadline passed.0 today
ai_verified_closedA 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).
ValueMeaning
createdThe row entered the served set for the first time after your cursor. Insert it.
updatedA 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.
withdrawnJOA stopped serving the row (quality verdict, duplicate hold, opt-out). The job may still say status live: stop showing it anyway.
delistedThe 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).
ValueMeaning
withdrawnThe row was withdrawn and may not be shown.
closedThe row was delisted.

remote

Source: CHECK listings_remote_type_check.
ValueMeaning
remoteThe posting says the job is done fully from home or from anywhere, with no regular office attendance.
hybridThe posting offers or requires a mix of office and remote work, for example 'remote possible', 'telework 2 days a week' or partial remote.
on_siteThe 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.
ValueMeaning
Full-timeFull time.
Part-timePart time.
ContractContract.
InternshipInternship.
TemporaryTemporary.

engagement (array)

Source: contractFilterVocab (api/contract.go), CHECK listings_engagement_values.
ValueMeaning
employeeAn employment relationship with an employer of record that runs payroll: the advertiser, a temp agency or an umbrella company.
vendorA service relationship: the person invoices as self-employed or through their own company (freelance, contractor, B2B, US 1099).
otherA stated relationship that is clearly neither: hybrid civil-law forms and dependent-contractor arrangements.

contract_category (array)

Source: contractFilterVocab, CHECK listings_contract_category_values.
ValueMeaning
permanentOpen-ended.
fixed_termFixed term.
project_basedFor a project.
seasonalSeasonal.
apprenticeshipApprenticeship.
internshipInternship.
otherAnother kind.

agency

Source: contractFilterVocab, CHECK listings_agency_values.
ValueMeaning
directThe employer hires directly.
agencyThrough a staffing agency.
umbrellaThrough an umbrella company (employed by it, usually understood as freelancing).

working_schedule

Source: contractFilterVocab, CHECK listings_working_schedule_values.
ValueMeaning
full_timeFull time.
part_timePart time.
flexibleFlexible hours.

seniority

Source: CHECK listings_seniority_check.
ValueMeaning
InternIntern, trainee, apprentice.
EntryJunior, graduate.
MidMid level.
SeniorSenior.
LeadLead, principal, staff.
ManagerManager, supervisor.
DirectorDirector, head of.
ExecutiveChief, president, founder.

salary_period

Source: CHECK listing_extract_salary_period_canonical and the values live listings carry.
ValueMeaning
hourPer hour.
dayPer day.
weekPer week.
monthPer month.
yearPer year.

salary_source

Source: CHECK listings_salary_source_check_v2, minus the values jobCols hides with NULLIF.
ValueMeaning
structuredA field the source published.
parsed_descriptionA figure the advert text states, read out by our rules.

source_type

Source: sourceTypeAlias (api/provenance.go), joa.providers.source_type.
ValueMeaning
atsAn applicant tracking system.
public_agencyA public employment service.
career_siteThe employer's own careers site.
aggregatorReserved: matches no rows today.
agencyReserved: matches no rows today.
unknownThe class is not recorded.

provider_type

Source: joa.providers.source_class of redistributable providers.
ValueMeaning
directCareers site (career_site).
employer_atsATS (source_type ats).
governmentPublic agency (public_agency).
aggregatorReserved.

last_verified_via

Source: joa.last_verified_via() over every input, lastVerifiedViaExpr (api/handlers.go).
ValueMeaning
ats_apiThe posting's record in its ATS API.
first_harvestNothing newer than the harvest that brought it in.
partner_feedThe employer's last push or heartbeat.
posting_pageThe posting's own page answered live.
source_listA fresh read of the employer's own job list included it.
verifierA check before 23 Oct 2026 whose method was not recorded.
board_apiAshby's own job board listed it.

language_basis

Source: langBasis (api/handlers.go).
ValueMeaning
textThe advert text.
title+countryAn English title in an English-speaking country; confidence capped at 0.85.
titleThe title (the text was missing or too short).
noneNo usable evidence.

posted_at_precision

Source: Job.PostedAtPrecision (api/handlers.go).
ValueMeaning
dateThe source states a date, not a time.

country_confidence

Source: countryConfidence (api/provenance.go).
ValueMeaning
highTwo methods agree.
lowA language model alone read the location text.

compensation_type

Source: compensationTypeValues (api/jobfilter.go).
ValueMeaning
commission_onlyPaid entirely by commission, no base salary.

field_sources values

Source: the src* constants (api/provenance.go).
ValueMeaning
publishedThe source stated it.
detectedlanguage only: our detector's reading of the text.
inferredWe produced it from other text or by a rule.
absentNo value.
llm_inferredcountry only: a language model alone read the location text.
unknowncountry only: the row has a country but nothing records where it came from.

embedding.reason

Source: reason constants (api/vectors.go).
ValueMeaning
no_vectorThe row has no vector yet.
vectors_unavailableThe vector service did not answer in time; repeat the call.

relevance.tier

Source: RelevanceInfo (api/handlers.go).
ValueMeaning
exactExact match.
synonymMatched a synonym.
abbreviationMatched an abbreviation.
typoMatched 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.
ValueMeaning
employerThe employer withdrew the role or opted out of JOA.
duplicateA duplicate of another listing JOA serves.
unverifiedJOA could not confirm it at its source recently; usually comes back once confirmed.
apply_linkIts apply link stopped working.
qualityIt no longer meets a serving rule (for example the link leads to a job board or an agency).
policyIts source may no longer be shown, or the row was removed.
closedIt has closed since it was withdrawn (it is in /v1/jobs/expired too).
otherIn transition at the moment you asked.
country_correctedWe 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.

4Change 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}.

In depthWhy it exists, what it is not, what people get wrong

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

FieldTypePresentValues or formatMeaningExample
changestringalwayscreated, updated, withdrawn, delistedWhat happened to the row after your cursor."updated"
jobjob objectalwaysThe 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).
correctionbooleanpresent only when truetrue 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.

FieldTypePresentValues or formatMeaningExample
idstringalwaysThe job id. All a copy needs to stop showing the row.
statusstringalwayswithdrawn, closedclosed when the row was delisted, withdrawn otherwise.

The /v1/changes page

KeyMeaning
dataThe events, oldest first.
next_sinceThe cursor to send as since next time. Echoes your own cursor when there is nothing new. Opaque.
countThe 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.

FieldTypePresentValues or formatMeaningExample
idstringalwaysThe id of a row that is closed now."00198eff-ea49-4ba5-832a-98fa7cba6162"
closed_atstringalwaysISO 8601 UTC timestamp with microseconds, e.g. 2026-11-08T04:55:48.123456ZWhen JOA recorded the closure. Also the feed position."2026-11-07T00:00:04.889337Z"
closed_reasonstringomitted when emptynot_seen, expired_upstream, apply_link_dead, superseded_by_jobtech_loader, aggregator_host, generic_apply_url, portal_apply_url, employer_closed, deadline_passed, ai_verified_closedWhy it closed."not_seen"
KeyMeaning
dataRows that are closed now, oldest closure first. A row that re-opened is no longer listed.
countItems on this page.
next_sinceThe cursor for the next call. Opaque.

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

FieldTypePresentValues or formatMeaningExample
idstringalwaysThe id of a row that left the served set without closing and is still out.
withdrawn_atstringalwaysISO 8601 UTC timestampWhen it left the served set. Also the feed position.
withdrawn_reasonstringalwaysemployer, duplicate, unverified, apply_link, quality, policy, closed, other, country_correctedA coarse public reason category.
KeyMeaning
dataRows that left the served set without closing and are still out, oldest first. A row that comes back is no longer listed.
countItems on this page.
next_sinceThe cursor for the next call. Opaque.

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

FieldTypePresentValues or formatMeaningExample
idstringalwaysThe job id you asked for.
statusstringalwaysAlways withdrawn: the row was served and no longer is, without closing.
withdrawn_atstringalwaysISO 8601 UTC timestampWhen it left the served set.
withdrawn_reasonstringalwaysemployer, duplicate, unverified, apply_link, quality, policy, closed, other, country_correctedA coarse public reason category.

5The /v1/jobs page, embeddings and relevance

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

In depthWhy it exists, what it is not, what people get wrong
FieldTypePresentValues or formatMeaningExample
dataarray of job objectsalways, may be nullThe job objects of this page.
next_cursorstringalways, may be nullOpaque cursor for the next page; null on the last page. Store it as a string, never parse it.
has_morebooleanalwaystrue when another page exists.
pagingstringomitted when emptyKeyless surface only: why no cursor is offered.
notestringomitted when emptyKeyless surface only: a human-readable note about paging.
total_estimateintegeromitted when emptyWith 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_statusstringomitted when emptyexact, at_least or timed_out.
location_ambiguousbooleanomitted when emptyWith city=: true when the matched rows span more than one country.
location_countriesarrayomitted when emptyWith city=: the matched set's country breakdown.
completenessobjectomitted when emptyWith require_fields=: how complete the page is for the fields you required.
next_sincestringomitted when emptyOnly 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[]searchHintomitted when emptyOnly 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)

FieldTypePresentValues or formatMeaningExample
modelstringalwaysThe embedding model, Qwen/Qwen3-Embedding-8B."Qwen/Qwen3-Embedding-8B"
dimintegeralwaysVector length, 1024.1024
normalizedbooleanalwaystrue: unit length, so cosine similarity equals the dot product.true
vectorarray of numbersalways, may be null1024 float32 valuesThe vector, or null when the row has none yet.
reasonstringomitted when emptyno_vector, vectors_unavailableWhy vector is null."no_vector"

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

FieldTypePresentValues or formatMeaningExample
scoreintegeralwaysOrdering score within one response only.
tierstringomitted when emptyexact, synonym, abbreviation, typoHow the query matched.

6The company object

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

In depthWhy it exists, what it is not, what people get wrong
FieldTypePresentValues or formatMeaningExample
slugstringalwaysThe company's readable key."h-r-block"
namestringalwaysDisplay name."H&R Block"
websitestringomitted when emptyThe company's domain, published only after we fetched it and found the company's name on it.
website_verifiedstringomitted when emptyYYYY-MM-DDThe date that check last passed.
logostringomitted when emptyLogo URL.
countrystringomitted when emptyISO 3166-1 alpha-2Headquarters country."US"
industrystringomitted when emptyIndustry label, published at confidence 0.6 or more."Retail"
org_typestringomitted when emptyOrganisation type label, published at confidence 0.6 or more."Enterprise"
sectorsarray of stringsalways, never null (empty array when none)The job categories the company hires in most.["Finance","Customer Support","Operations & Admin"]
open_rolesintegeralwaysRoles retrievable from this API now.19729
own_site_rolesintegeralwaysVacancies seen on the company's own careers page under a source JOA does not redistribute. Evidence of hiring, not inventory.0
careers_urlstringomitted when emptyThe company's careers page.
source_typesarray of stringsalways, never null (empty array when none)The source types its roles come from.["career_site","ats"]
first_seenstringomitted when emptyYYYY-MM-DDWhen the company first appeared."2026-08-02"
closure_historyarray of closure objectsomitted when emptyRecent closed roles, on GET /v1/companies/{slug} only.
seo_indexablebooleanonly on the keyless website read, never on /v1Website use only: whether the public company page asks search engines to index it.
seo_closed_180dintegeronly on the keyless website read, never on /v1Website use only: closures in 180 days, an input of seo_indexable.
seo_last_changestringonly on the keyless website read, never on /v1Website use only: an input of seo_indexable.

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

FieldTypePresentValues or formatMeaningExample
slugstringalwaysThe closed job's slug.
titlestringalwaysThe closed job's title.
closed_atstringalwaysWhen it closed.
closed_reasonstringalways, may be nullnot_seen, expired_upstream, apply_link_dead, superseded_by_jobtech_loader, aggregator_host, generic_apply_url, portal_apply_url, employer_closed, deadline_passed, ai_verified_closedWhy it closed.

7How 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.

In depthWhy it exists, what it is not, what people get wrong
  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.

This page was rendered 17 November 2026, 07:47 UTC. Every figure on it comes from the endpoint named beside it, and every published request is re-sent against the live API before this site is allowed to build. If something here is wrong, the thumbs-down above reaches a person.