Search recipes

Two endpoints search the same index:

Endpoint	Filters	Best for
`GET /api/jobs`	Query string, comma-separated multi-values	URL-shareable queries, light integrations
`POST /api/jobs/search`	Typed JSON body with include/exclude and range filters	Filter UIs and anything programmatic

Both are page-based and ranked by relevance unless you set sort. They reach at most 100,000 results deep (page × page_size, see Pagination). To export the whole corpus, use the feed: it costs the same per job, and its cursor doesn’t skip or repeat jobs as records change.

Filter values match literally. An unrecognized value returns 200 with total: 0, not an error. Send the canonical keys from Enums, not the display values on a job.

Parameter equivalence

Concept	`GET` query param	`POST` body field
Text query	`q` (single string)	`queries` (string array, OR’d)
Location	`location` (single string)	`locations` (string array)
Sources	`sources` (comma-separated)	`sources` (string array)
Work model	`work_model` (comma-separated)	`work_models` (string array)
Employment type	`employment_type` (comma-separated)	`employment_types` (string array)
Experience level	`experience_level` (comma-separated)	`experience_levels` (string array)
Language	`language` (comma-separated)	`languages` (string array)
Skills	`skills` (comma-separated)	`skills` (include/exclude object)
Industries	`industries` (comma-separated)	`industries` (include/exclude object)
Company category	`company_categories` (comma-separated)	`company_categories` (include/exclude object)
Job category	`job_categories` (comma-separated)	`job_categories` (include/exclude object)
Job subcategory	`job_subcategories` (comma-separated)	`job_subcategories` (include/exclude object)
Occupation	`occupation_ids` (comma-separated)	`occupation_ids` (include/exclude object)
Companies	Not available on `GET`	`companies` (include/exclude object)
Salary	`min_salary_usd`, `max_salary_usd`	`salary_usd` (`{min, max}` object)
Posted window	`posted_after`, `posted_before`	`posted_after`, `posted_before`
Discovered window	`discovered_after`, `discovered_before`	`discovered_after`, `discovered_before`
Search scope	`search_description` (default `true`)	`search_description` (default `true`)
Facet selection	`include_facets` (comma-separated)	`include_facets` (string array)
Field selection	`include_fields` (comma-separated)	`include_fields` (string array)
Description format	`description_format` (default `markdown`)	`description_format` (default `markdown`)
Sort	`sort` (default `relevance`)	`sort` (default `relevance`)
Pagination	`page` (default 1), `page_size` (default 25, max 100)	`page`, `page_size` (same defaults and max)

Unknown parameters and body fields are ignored, and listed in warnings (code unknown_request_fields) and the X-Jobo-Warnings header.
POST arrays are not comma-split. "employment_types": ["full-time,contract"] is one literal value and matches nothing; write ["full-time", "contract"].
GET filters only include. To exclude skills, industries, company categories, job categories, job subcategories or occupations, use the exclude side of the POST object.

How text queries match

Query	Matches
`data engineer` (default)	Title, curated alternative titles, company name, popular skills and summary, with typo tolerance
`data engineer` with `search_description=false`	The job’s own title plus curated same-role alternative titles
`"Quantitative Developer"` (double-quoted)	That exact phrase, contiguous, in the job title. No typos, partial words or alternative titles
`["software engineer", "-staff"]`	Software engineer jobs, minus any job containing `staff` or a common form such as `staffing` or `staffed`

A - entry with several words excludes jobs that contain any of them. Neither mode searches the full description. Set search_description=false when you pass exact job titles: Android Developer then also finds Android Engineer, but not jobs that only mention Android as a skill or in the summary. With the default sort, jobs that match every word of a query rank first. Partial matches fill the tail only when a query has no full match inside your filters (a short posted_after range, for example), so take results from the top.

Quoted phrases match titles only

{ "queries": ["\"Quantitative Developer\"", "\"Quant Developer\""] }

Only jobs whose title contains either phrase come back. You can mix quoted and unquoted entries; each is evaluated on its own and the results are combined:

{ "queries": ["\"Quant Developer\"", "machine learning engineer"] }

On GET /api/jobs, put the quotes inside the value: ?q="Quantitative Developer".

queries takes at most 10 positive entries. More returns a 400 instead of dropping the extras. Negative - entries don’t count toward the limit.

Recipes

The Python samples use the Python SDK and reuse the client from the first recipe. Parameters the 4.0.0 SDKs don’t send, such as sort and the occupation filters, have curl or JSON samples only.

Keyword plus location

curl "https://connect.jobo.world/api/jobs?q=data+engineer&location=Seattle&page_size=10" \
  -H "X-Api-Key: $JOBO_API_KEY"

import os
from jobo_enterprise import JoboClient

with JoboClient(api_key=os.environ["JOBO_API_KEY"]) as client:
    results = client.search.search(q="data engineer", location="Seattle", page_size=10)
    print(f"{results.total} matches across {results.total_pages} pages")
    for job in results.jobs:
        print(f"  {job.title} — {job.company.name} ({job.workplace_type})")

location and locations use the same resolver as GET /api/locations/geocode, so you can check how a string will be read before you search. See Resolve locations.

Remote senior roles in a salary band

curl -G "https://connect.jobo.world/api/jobs" \
  -H "X-Api-Key: $JOBO_API_KEY" \
  --data-urlencode "q=backend engineer" \
  --data-urlencode "work_model=remote" \
  --data-urlencode "experience_level=senior" \
  --data-urlencode "employment_type=full-time" \
  --data-urlencode "min_salary_usd=150000" \
  --data-urlencode "max_salary_usd=250000"

results = client.search.search(
    q="backend engineer",
    work_model="remote",
    experience_level="senior",
    employment_type="full-time",
    min_salary_usd=150_000,
    max_salary_usd=250_000,
)

Experience levels take the canonical key: senior, not senior level.

Since 4.0.0, the client enums (WorkModel, EmploymentType, ExperienceLevel) send canonical values: EmploymentType.FULL_TIME sends full-time, and ExperienceLevel.INTERN and EmploymentType.FREELANCE exist. On 3.x and earlier, pass string literals instead of the enums (Upgrading to 4.0.0).

Include and exclude skills

{
  "queries": ["backend developer"],
  "skills": { "include": ["python", "go"], "exclude": ["php"] }
}

from jobo_enterprise import InclusionExclusionFilter

results = client.search.search_advanced(
    queries=["backend developer"],
    skills=InclusionExclusionFilter(include=["python", "go"], exclude=["php"]),
)

This include/exclude object is POST-only. include entries are OR’d, and jobs matching any exclude entry are removed. companies, industries, company_categories, job_categories, job_subcategories and occupation_ids take the same object.

Target or exclude specific employers

{
  "queries": ["software engineer"],
  "companies": { "include": ["FedEx", "Fidelity Investments"] }
}

companies works on POST only. Each entry is matched by its form:

Entry	Example	Matched against
Jobo company id	A GUID, the same as `company.id` on a job	The company id
Website domain or URL	`fedex.com`, `https://www.fedex.com/careers`	The company’s stored website domain
Anything else	`FedEx`	The company’s display name

A domain ignores a leading www. but not other subdomains: careers.fedex.com doesn’t match fedex.com. Use the main domain.
A name must match the whole company name. Case, accents, punctuation and common trailing legal suffixes are ignored, so FedEx Corporation, fedex and FedEx, Inc. find the same companies.
It is not a partial match: Glenmark doesn’t find Glenmark Pharmaceuticals, and Fidelity finds the company called Fidelity, not every Fidelity* employer.

To drop staffing agencies, exclude them:

{
  "queries": ["software engineer"],
  "companies": { "exclude": ["Acme Staffing", "Generic Recruiting Co"] }
}

Entries that match nothing never fail the request. When every include entry misses, you get 200 with zero jobs, not a 400. Check warnings and filters.companies.unmatched.

{
  "jobs": [],
  "total": 0,
  "warnings": [
    {
      "code": "companies_unmatched",
      "field": "companies.include",
      "message": "The entry in companies.include matched no company (\"Glenmark\"). Names are matched on the whole company name, so \"Bain\" does not find \"Bain & Company\". Search without the companies filter to find the exact stored values."
    }
  ],
  "filters": { "companies": { "unmatched": ["Glenmark"] } }
}

`warnings[].code`	Cause
`companies_unmatched`	An `include` entry matched no company.
`companies_exclude_unmatched`	An `exclude` entry matched no company, so it excludes nothing.
`companies_outside_sources`	The companies are on none of the requested `sources`, so the result is provably empty.

For example, FedEx is indexed on Workday, so FedEx with sources: ["greenhouse"] returns companies_outside_sources and no jobs, however you spell the name. To find a stored spelling, search the name as free text and read company.name: q=Glenmark surfaces jobs at Glenmark Pharmaceuticals.

Filter by occupation

curl -G "https://connect.jobo.world/api/jobs" \
  -H "X-Api-Key: $JOBO_API_KEY" \
  --data-urlencode "job_categories=Healthcare" \
  --data-urlencode "location=Chicago"

Every classified job carries an occupation in a three-level taxonomy, such as Healthcare › Nursing › Registered Nurse. Filter on any level:

Level	Filter	Takes
Category	`job_categories`	The category name, for example `Healthcare`
Subcategory	`job_subcategories`	The subcategory name, for example `Nursing`
Occupation	`occupation_ids`	The occupation id, for example `esco:8d3e8aaa-791b-4c75-a465-f3f827028f50`

The free GET /api/occupations lists every value. Cache it and refetch now and then: its version changes when occupations or the hierarchy change, but display names can improve without a new version. On POST you can also exclude. Every nursing job except registered nurse roles:

{
  "job_subcategories": { "include": ["Nursing"] },
  "occupation_ids": { "exclude": ["esco:8d3e8aaa-791b-4c75-a465-f3f827028f50"] }
}

Matching is exact but ignores case: healthcare works, Health care matches nothing.
Filter occupations by id, never by name. Names can improve between taxonomy releases; ids don’t.
A job without an occupation never matches an include list.
q and queries don’t search occupation names. To find every job of one occupation, whatever the employer called it, use occupation_ids.
With a sandbox key, POST /api/jobs/search ignores these filters (with an unknown_request_fields warning) and returns no occupation facets. Test them with a live key.

Four subcategory names contain a comma: Libraries, Archives & Museums, Film, TV & Stage Production, Sports, Fitness & Recreation and Environmental, Health & Safety. GET /api/jobs splits job_subcategories on commas, so these match nothing there. Filter them on POST /api/jobs/search, where each array entry is one value.

Open-ended salary range

{ "salary_usd": { "min": 200000 } }

from jobo_enterprise import RangeFilter

results = client.search.search_advanced(salary_usd=RangeFilter(min=200_000))

Omit either bound. Jobs without disclosed compensation never match a salary filter.

Posted window vs discovered window

{
  "queries": ["backend engineer"],
  "posted_after": "2026-06-01T00:00:00Z",
  "posted_before": "2026-07-01T00:00:00Z"
}

Filters	Compares against	Use when
`posted_after`, `posted_before`	The employer’s posting date, which some platforms don’t expose	You need the employer’s date
`discovered_after`, `discovered_before`	When Jobo first indexed the job, which every job has	You can’t afford to miss jobs

To page through a discovered window without jobs shifting between pages, add "sort": "discovered_asc". See Stable pages over a fixed window.

Everything at once

{
  "queries": ["backend engineer", "platform engineer"],
  "locations": ["San Francisco", "New York", "Seattle"],
  "sources": ["greenhouse", "lever", "ashby"],
  "skills": { "include": ["go", "rust", "kubernetes"], "exclude": ["php"] },
  "companies": { "exclude": ["Acme Staffing"] },
  "work_models": ["remote", "hybrid"],
  "employment_types": ["full-time"],
  "experience_levels": ["senior", "lead"],
  "salary_usd": { "min": 150000, "max": 300000 },
  "posted_after": "2026-01-15T00:00:00Z",
  "page": 1,
  "page_size": 50
}

Iterate every match

for job in client.search.iter_jobs(
    queries=["backend engineer"],
    locations=["London"],
    page_size=100,
):
    print(job.title, job.company.name)

iter_jobs pages through the results for you.

A page past the 100,000-result depth silently returns the last reachable page again, so on a larger result set iter_jobs yields repeated jobs. Narrow the filters to keep total under 100,000, or use the feed.

Shrinking the response

description dominates payload size; dropping it is the biggest saving for high-volume search. include_fields keeps only the non-core fields you name. Core fields (id, title, company, locations, compensation, dates, source, flags) always come back.

`include_fields`	Result
Omitted	Full job, every field. The default.
`["description","benefits"]`	Core plus `description` and `benefits`.
`[]` (or empty on `GET`)	Core fields only.

The five omittable fields are description, summary, qualifications, responsibilities and benefits. Unknown names are dropped.
On GET, pass a comma-separated string (?include_fields=description,benefits), or ?include_fields= for core fields only.
A non-core field you didn’t request is still present but empty: description is "", summary is null, and the list fields are [].

facets holds server-computed counts, keyed by canonical value.

Facet key	Faceted on	Default
`work_model`	Work model	Yes
`experience_level`	Experience level	Yes
`employment_type`	Employment type	Yes
`sources`	`provider_id`	Yes
`industries`	Company industries	Opt-in
`skills`	Skill names	Opt-in (high cardinality, adds latency)
`countries`	Job country	Opt-in
`company_categories`	Company business model (`b2b`, `saas`, …)	Opt-in
`job_categories`	Occupation category	Opt-in
`job_subcategories`	Occupation subcategory	Opt-in
`occupations`	Occupation id	Opt-in

`include_facets`	Result
Omitted	The four defaults.
`["skills"]`	Only `skills`.
`[]` (or empty on `GET`)	No facets: `"facets": {}`.

{
  "facets": {
    "work_model": [
      { "key": "remote", "count": 5230 },
      { "key": "hybrid", "count": 2847 },
      { "key": "onsite", "count": 1540 }
    ],
    "experience_level": [
      { "key": "senior", "count": 4521 },
      { "key": "mid", "count": 3892 }
    ]
  }
}

A facet key goes straight back in as a filter value; the display values on a job don’t (see Enums). countries keys are lowercased country names (united states): pass them back as locations. company_categories keys go into the company_categories include/exclude filter. job_categories and job_subcategories keys are lowercased names (healthcare, nursing); occupations keys are occupation ids. Each goes back into the filter of the same name (occupations into occupation_ids). Only these buckets carry two extra fields:

Field	Value
`name`	The display name as the taxonomy spells it (`Healthcare` for `healthcare`), or the occupation’s name
`parent`	The key one level up: a subcategory’s category, or an occupation’s subcategory. Categories have none.

{
  "facets": {
    "job_categories": [
      { "key": "healthcare", "count": 41230, "name": "Healthcare" }
    ],
    "job_subcategories": [
      { "key": "nursing", "count": 19876, "name": "Nursing", "parent": "healthcare" }
    ],
    "occupations": [
      {
        "key": "esco:8d3e8aaa-791b-4c75-a465-f3f827028f50",
        "count": 11402,
        "name": "Registered Nurse",
        "parent": "nursing"
      }
    ]
  }
}

Request all three ("include_facets": ["job_categories", "job_subcategories", "occupations"]) and nest them by parent to build a category › subcategory › occupation filter tree from one response.

Unknown facet names are silently dropped. If include_facets holds only unknown names (say, the typo work_models), you get no facets, not the defaults.
Each facet returns at most 8 buckets, with approximate counts. Take exact totals from total, not from summed facet counts.
With that cap, a subcategory’s parent may be missing from the category buckets. Use GET /api/occupations for the full tree.
A facet with no buckets is left out of facets, not returned as an empty array.

Building this with an AI coding assistant?

Copy-paste prompts that hand your assistant the full search contract: add job search to your app, or audit an existing integration for silent failures.

Get started

How-to guides

Build with AI assistants

Connectors

Resources

Parameter equivalence

How text queries match

Quoted phrases match titles only

Recipes

Keyword plus location

Remote senior roles in a salary band

Include and exclude skills

Target or exclude specific employers

Filter by occupation

Open-ended salary range

Posted window vs discovered window

Everything at once

Iterate every match

Shrinking the response

Facets

Occupation facets

Facet limits

Building this with an AI coding assistant?

​Parameter equivalence

​How text queries match

​Quoted phrases match titles only

​Recipes

​Keyword plus location

​Remote senior roles in a salary band

​Include and exclude skills

​Target or exclude specific employers

​Filter by occupation

​Open-ended salary range

​Posted window vs discovered window

​Everything at once

​Iterate every match

​Shrinking the response

​Facets

​Occupation facets

​Facet limits

Building this with an AI coding assistant?

Parameter equivalence

How text queries match

Quoted phrases match titles only

Recipes

Keyword plus location

Remote senior roles in a salary band

Include and exclude skills

Target or exclude specific employers

Filter by occupation

Open-ended salary range

Posted window vs discovered window

Everything at once

Iterate every match

Shrinking the response

Facets

Occupation facets

Facet limits