Skip to main content
POST
cURL

Authorizations

​
X-Api-Key
string
header
required

Your Jobo API key. Create one in the dashboard under Developers → API Keys. Live keys start with jbe_live_ and sandbox keys with jbe_test_.

Body

application/json
​
queries
string[] | null

Free-text queries, OR'd together. Each entry matches broadly with typo tolerance; search_description chooses the fields. Double-quote an entry ("\"Quantitative Developer\"" in JSON) for an exact, contiguous phrase match on the job title only. Prefix an entry with - to exclude it. Up to 10 positive entries; more returns 400, and - entries don't count. See How text queries match.

​
search_description
boolean
default:true

Which fields queries match. true (default): the title, curated alternative titles, company, popular skills and summary, so python finds a Software Engineer job that lists Python as a skill. false: the job's own title and curated same-role alternative titles only, so Android Developer also finds Android Engineer but not a job that only lists Android as a skill. Use false when you pass exact job titles.

Double-quoted entries match the literal job title only, without alternative titles, in either mode. See How text queries match.

​
locations
string[] | null

Location strings, resolved by the same geocoder as GET /api/locations/geocode. See Resolve locations.

​
sources
string[] | null

Restrict to these ATS provider ids (e.g. greenhouse, lever, workday). See Sources for every id.

​
skills
object | null

Include/exclude skills filter

​
companies
object | null

Include/exclude companies. Each entry is matched by its form:

  • A GUID (any format or casing) matches the Jobo company id, as in company.id and filters.companies.matched.
  • A domain or URL (fedex.com, https://www.fedex.com/careers) matches the website domain, ignoring scheme, path, port and a leading www.. Other subdomains count, so use the main domain. A value that parses as a domain is never retried as a name.
  • Anything else matches the whole company name, ignoring case, accents, punctuation and trailing legal suffixes (Inc, Corp, Ltd, plc, GmbH, …). Not a partial match: Glenmark does not find Glenmark Pharmaceuticals.

Unmatched entries never fail the request. Unmatched include entries are listed in filters.companies.unmatched with a companies_unmatched warning; if every one misses, you get 200 with zero jobs, not 400. An unmatched exclude entry excludes nothing (companies_exclude_unmatched). Companies on none of the requested sources (a Workday company with sources: [greenhouse]) return nothing and are reported as companies_outside_sources.

See Search recipes.

​
industries
object | null

Include/exclude company-industry filter. Matched on the whole industry name, case-insensitively — not a partial match.

​
company_categories
object | null

Include/exclude filter on the hiring company's business model (company.categories), such as b2b, b2c, b2b2c, saas, marketplace or service-provider. Exact, case-insensitive match.

​
job_categories
object | null

Include/exclude filter on the job's occupation category (occupation.category, e.g. Healthcare). Exact, case-insensitive match. GET /api/occupations lists every value. Jobs without an occupation never match an include list.

​
job_subcategories
object | null

Include/exclude filter on the job's occupation subcategory (occupation.subcategory, e.g. Nursing). Exact, case-insensitive match. GET /api/occupations lists every value.

​
occupation_ids
object | null

Include/exclude filter on occupation id (occupation.id, e.g. esco:8d3e8aaa-791b-4c75-a465-f3f827028f50). Use ids, not names: names can improve between taxonomy releases, ids don't. GET /api/occupations lists every id.

​
work_models
enum<string>[] | null

Filter by work model: remote, hybrid, onsite

Available options:
remote,
hybrid,
onsite
​
employment_types
enum<string>[] | null

Filter by employment type: full-time, part-time, contract, internship, freelance, temporary

Available options:
full-time,
part-time,
contract,
internship,
freelance,
temporary
​
experience_levels
enum<string>[] | null

Exact-match experience-level filter. Canonical values are intern, entry, mid, senior, lead, and executive.

Available options:
intern,
entry,
mid,
senior,
lead,
executive
​
languages
string[] | null

Filter by description language, as ISO 639-1 codes (en, de, fr). Language names and locales (English, en-US) are mapped to their code. null = all jobs.

​
salary_usd
object | null

Annualized USD range-overlap filter. A job matches when its disclosed salary range intersects the requested range. Jobs without disclosed compensation are excluded.

​
posted_after
string<date-time> | null

Only return jobs whose employer posting date is on or after this date

​
posted_before
string<date-time> | null

Only return jobs whose employer posting date is on or before this date

​
discovered_after
string<date-time> | null

Only return jobs first indexed on or after this UTC timestamp

​
discovered_before
string<date-time> | null

Only return jobs first indexed on or before this UTC timestamp

​
sort
enum<string>
default:relevance

Result order. relevance (default) ranks by match quality, or by most recently updated when there are no queries. Jobs that match every word of a query rank first, so take results from the top. Relevance order shifts as jobs update, so deep paging can skip or repeat a job. discovered_asc and discovered_desc order by created_at, which never changes: pair them with discovered_after / discovered_before for stable pages.

Available options:
relevance,
discovered_asc,
discovered_desc
​
page
integer
default:1
Required range: x >= 1
​
page_size
integer
default:25
Required range: 1 <= x <= 100
​
include_facets
enum<string>[] | null

Facets to return. Omit (or null) for the defaults: work_model, experience_level, employment_type and sources. Pass [] for none. Every other facet is computed only when requested. Each facet returns at most 8 buckets, and unknown names are ignored.

A bucket key goes straight back in as a filter value: countries keys (lowercased names such as united states) as locations, occupations keys as occupation_ids. Occupation buckets also carry name and parent. See Facets.

Available options:
work_model,
experience_level,
employment_type,
sources,
industries,
skills,
countries,
company_categories,
job_categories,
job_subcategories,
occupations
​
include_fields
enum<string>[] | null

Non-core fields to return. Omit (or null) for the full job. Pass a subset to keep only those, or [] for core fields only. Unknown names are ignored. Excluded fields are still present but empty: description is "", summary is null, responsibilities and benefits are [], and qualifications has empty buckets. See Shrinking the response.

Available options:
description,
summary,
qualifications,
responsibilities,
benefits
​
description_format
enum<string>
default:markdown

Format of each job's description. markdown (default) returns it as stored. html renders it to HTML on the fly: raw HTML in the source is escaped and only http(s), mailto and relative URLs are kept.

Available options:
markdown,
html

Response

Paginated list of matching jobs with optional facets

​
jobs
object[]
required
​
total
integer<int64>
required
​
page
integer
required
​
page_size
integer
required
​
total_pages
integer
required
​
facets
object
required
​
warnings
object[] | null

Non-fatal problems with the request. Omitted when there is nothing to report. The same codes are sent, comma-separated, in the X-Jobo-Warnings response header, so a client can branch without parsing the body.

​
filters
object | null

How the server interpreted the filters that needed resolving. Present only when a companies filter was supplied.