> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letsfind.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and filters

> Find open jobs by keyword, place, pay, occupation and more.

`GET /v1/jobs` returns open jobs that match every filter you send.

```bash theme={null}
curl "$BASE_URL/v1/jobs?q=sales%20manager&country=GB&country=IE&workplaceType=hybrid" \
  -H "Authorization: Bearer $API_KEY"
```

## How filters combine

* Different filters must all match. `country=GB&workplaceType=hybrid` keeps hybrid jobs in the UK.
* A filter you repeat matches any of its values. `country=GB&country=IE` keeps jobs in the UK or Ireland.
* A job in several places matches when any of its places matches.
* Filter values come from the jobs, not from a fixed list. Ask [`GET /v1/facets`](https://docs.letsfind.work/facets) which values exist.

## Keyword search

`q` looks in the title, the company name and the department.

* It finds any part of a word, in any case: `q=account` finds "Accountant" and "Key Account Manager".
* Every word must match: `q=senior nurse` needs both words.
* It works in any language and script.
* It does not search the full job text.

## All filters

| Param | Type | What it keeps | Facet |
| - | - | - | - |
| `q` | string | Words to find in the title, company or department: any part of a word, any case. Every word must match. | |
| `excludeQ` | string | Words to find in the title, company or department: any part of a word, any case. Every word must match. | |
| `title` | string | Words to find in the title: any part of a word, any case. Every word must match. | |
| `excludeTitle` | string | Words to find in the title: any part of a word, any case. Every word must match. | |
| `department` | string | Words to find in the department: any part of a word, any case. Every word must match. | |
| `excludeDepartment` | string | Words to find in the department: any part of a word, any case. Every word must match. | |
| `text` | string | Whole words to find in the job text, any case, any language. Every word must match. | |
| `excludeText` | string | Whole words to find in the job text, any case, any language. Every word must match. | |
| `company` | string, repeatable | Company name, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `excludeCompany` | string, repeatable | Company name, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | |
| `agency` | boolean | true: only jobs of staffing and recruiting firms; false: none of them. Firms are known by name (a list of large firms and the words such firms put in their names). | |
| `ats` | string, repeatable | Applicant tracking system, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `excludeAts` | string, repeatable | Applicant tracking system, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | |
| `workplaceType` | string, repeatable | Workplace type, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `employmentType` | string, repeatable | Employment type, any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `language` | string, repeatable | Language of the job text (ISO 639-1), any case. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `location` | string, repeatable | A place in any common form: a city ("Munich", "München, DE"), a region in any language or its ISO 3166-2 code ("Bavaria", "Bayern", "DE-BY"), a country or its code ("Germany", "DE"), a group of countries ("Europe", "EU"). "Remote" or "Remote in Germany" keep remote jobs only. Repeat the param to match any of several places. | |
| `excludeLocation` | string, repeatable | A place in any common form: a city ("Munich", "München, DE"), a region in any language or its ISO 3166-2 code ("Bavaria", "Bayern", "DE-BY"), a country or its code ("Germany", "DE"), a group of countries ("Europe", "EU"). "Remote" or "Remote in Germany" keep remote jobs only. Repeat the param to match any of several places. | |
| `country` | string, repeatable | Country (ISO 3166-1 alpha-2, any case); a job in several places matches any. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `region` | string, repeatable | Region or state, as GET /v1/facets lists it, or its ISO 3166-2 code ("DE-BY"). Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `city` | string, repeatable | City, as GET /v1/facets lists it. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `occupation` | string, repeatable | ISCO-08 occupation code or group prefix ("25" holds "2512"). Repeat to match any. | yes |
| `excludeOccupation` | string, repeatable | ISCO-08 occupation code or group prefix ("25" holds "2512"). Repeat to match any. | |
| `salaryMinEur` | integer | Yearly pay at least this, in EUR (the middle of the employer's range, converted at the day's rate). Jobs without pay are left out. | |
| `industry` | string, repeatable | Industry of the company, as Wikidata names it ("software industry"); jobs of companies with no known industry are left out. Repeat the param to match any of several values; GET /v1/facets lists the values in use. | yes |
| `companySize` | string, repeatable | Headcount band of the company. Repeat to match any; jobs of companies with no known headcount are left out. | yes |
| `canonical` | boolean | true: one job per duplicate group (the first posted) and every job without duplicates; false: only the other jobs of each group. Without it, all jobs. A group is the same company, title and places on two or more boards, posted within 30 days. | |
| `postedAfter` | date-time or date | Jobs posted (or first seen, when earlier or undated) at or after this date or time, UTC | |
| `ids` | integer, repeatable | Job ids. Repeat the param to match any, up to 100. | |
| `url` | string, repeatable | The job's URL on its board or its application form URL, exactly as the job has it. Repeat the param to match any, up to 10. | |
| `benefit` | string, repeatable | Benefit the job text offers, read by rules: health, retirement, paid\_time\_off, wellness. Repeat the param to match any. | yes |
| `visaSponsorship` | boolean | Read by rules from the job text. true: jobs that say they sponsor visas; false: jobs that say they do not, or that need the right to work already. Jobs whose text says nothing are left out. | yes |

Notes on some filters:

* `country` takes ISO 3166-1 alpha-2 codes such as `US`, `DE` or `IN`.
* `region` and `city` take the names exactly as `GET /v1/facets` lists them.
* `occupation` takes ISCO-08 codes. A short code matches the whole group: `2` is all professionals, `22` is health professionals, `2221` is nursing professionals.
* `salaryMinEur` compares yearly pay in euros, so you can compare jobs paid in any currency or per hour. Jobs that publish no pay are left out when you use it.
* `postedAfter` takes a date (`2026-11-01`) or a date and time with a time zone.
* `ids` (up to 100) and `url` (up to 10) look up jobs you already know. `url` matches the job's board URL or its application form URL, exactly.
* `benefit` and `visaSponsorship` match [fields read from the job text](https://docs.letsfind.work/text-fields.md). `visaSponsorship` leaves out jobs whose text says nothing about visas.
* A param the API does not know (a typo, or a filter that is gone) is an error, `400`, so a search never runs without the filter you meant.

## Sort

`sort=newest` (the default) or `sort=oldest`, by the date the employer posted the job. When the employer gives no date, or we saw the job before that date, the date we first saw it counts.

## One job

`GET /v1/jobs/{id}` returns one open job. A closed job returns `404`.

## Full text

Jobs come with a short `snippet`. If we turned on full text for your account, add `fullText=true` to `GET /v1/jobs`, `GET /v1/jobs/{id}` or `GET /v1/changes`: each job then also has `description`, its full text. Other accounts get `403`. Ask us to turn it on.

## Companies

`GET /v1/companies` lists companies that have open jobs, with their board and number of open jobs. Filter by part of the name with `q` and by `ats`. Use a company's `name` in the `company` filter of `GET /v1/jobs`.

```bash theme={null}
curl "$BASE_URL/v1/companies?q=bank" -H "Authorization: Bearer $API_KEY"
```

## Freshness

We read each employer's board about once a day; boards with no new job for a week, every two days. A new job is in the API as soon as we read its board. Answers are cached for up to 10 minutes, so the same request in that time returns the same answer.

A job stays in the API while its board lists it, up to 183 days after it was posted (or first seen). A job its board no longer lists leaves the results, usually at the next read of that board.

How fast each ATS reaches the API: [measured freshness](https://docs.letsfind.work/sources.md#how-fresh).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.