Choosing the Right Filters for Your Use Case

The /jobs endpoint supports a wide filter surface — title, location, remote, seniority, salary, employment type, freshness. Which ones actually matter depends on what you're building. This guide is a practical map from product type to filter combination, not a full parameter reference (see the Jobs API reference for that). All the requests below assume you already have an API key from your dashboard, passed as $CLEANJOBDATA_API_KEY.

Start with the Product, Not the Filter List

Picking filters in the wrong order — starting from "what's available" instead of "what does this product need" — tends to produce over-broad queries that need client-side post-filtering. Work backward from the page you're building instead.

A General Job Board

Broad coverage, minimal server-side scoping, most filtering happens in the user's search UI:

curl "https://api.cleanjobdata.com/jobs?limit=50" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Expose title, location, remote, and experience_level as user-facing controls. Don't pre-filter on the server beyond what the user has selected — a general board's value is breadth.

A Niche Board (Role, Stack, or Region)

Scope the niche in the server-side query itself, not in the UI — the niche is the product, not a filter option:

curl "https://api.cleanjobdata.com/jobs?title=React&remote=true&limit=50" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Combine title with country_id/city_id for a regional niche, or with experience_level for a seniority-scoped one (e.g. a senior-only board). Keep the scoping filters fixed in your backend query, and expose only secondary filters (salary, freshness) to the user.

A Job Alert System

Freshness matters more than breadth — you're checking for what's new since the last run, not browsing the full index:

curl "https://api.cleanjobdata.com/jobs?title=engineer&created_max_age=1d" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Combine the user's saved search filters (title, location, remote, salary minimum) with created_max_age, sized to your alert run's interval — this checkpoints on ingestion time, so a listing that finishes processing after your last run still gets caught even if its published date is older. See Syncing Job Data In Depth for the full pattern, including the closed-listing edge case that saved searches need to handle too.

A Salary Benchmarking or Analytics Tool

Salary and seniority matter most; location precision matters more than remote status:

curl "https://api.cleanjobdata.com/jobs?title=engineer&experience_level=SE&city_id=123" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Filter tightly on role and seniority so you're comparing like-for-like, and use city_id rather than free-text location for market comparisons — city-level precision is what makes the benchmark meaningful. Not every listing includes salary data, so treat missing salary_min/salary_max as "undisclosed," not zero.

A Browser Extension or Contextual Widget

Small, cheap, tightly scoped requests — you're not building a search experience, you're answering one specific question per request:

curl "https://api.cleanjobdata.com/jobs?title=engineer&limit=5&fields=id,title,company,salary_min,salary_max,location" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Use fields aggressively here — a widget rendering three fields shouldn't fetch the full default projection. For "jobs at this specific employer," see the employer-scoping options below rather than pulling a broad result set and filtering client-side.

Filtering by a Specific Employer

Three filters scope a query to one company server-side:

• company_website_url — matches by the employer's real registrable domain (a bare domain or full URL both work). This is the reliable option when you know the company's actual site.
• employer_id — exact match against a company's internal ID, comma-separated for up to 100 at once. You won't have this ahead of time, but most job responses include employer_id at the top level (a job whose employer wasn't resolved to a company record can have it null), so once you've seen a job with one, you can filter future queries to that exact employer (or set of employers).
• company_name — substring match on company name. Useful for a user-facing "search by company" box, but less precise than the two above since it's fuzzy — prefer company_website_url or employer_id when you have them.

curl "https://api.cleanjobdata.com/jobs?company_website_url=acme.com&limit=20" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

There's also a separate domain filter, easy to confuse with company_website_url — don't use it for company-scoping. It matches each job's application_url domain, which for many ATS-hosted boards is the ATS's own hosting domain (e.g. boards.greenhouse.io), not the employer's real site. company_website_url is the one that actually answers "jobs at this company."

remote Is a Boolean — remote_type Is a Finer Filter

remote=true filters on has_remote, a plain yes/no. If your product needs to distinguish kinds of remote — fully distributed vs. remote-but-restricted-to-one-country vs. remote-within-a-region vs. hybrid — use remote_type instead, which accepts one of four values: fully_remote, remote_country, remote_region, or hybrid.

curl "https://api.cleanjobdata.com/jobs?title=engineer&remote_type=fully_remote" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

This matters for products like "remote jobs open to anyone worldwide" (fully_remote) vs. "remote jobs I can legally take from my country" (remote_country/remote_region, combined with your own location filter) — remote=true alone can't make that distinction, since a hybrid role and a fully-distributed one both satisfy it.

Filters That Combine Well vs. Filters That Fight Each Other

title + remote + experience_level combine cleanly since they narrow independent dimensions. location/city_id/country_id and remote=true can work against each other depending on intent — deciding whether a remote role "counts" for a specific city depends on whether you want remote roles headquartered there or remote roles open to anyone. Check has_remote and the locations array (see Job Location Normalization) rather than assuming remote=true alone answers that question.

The Short Version

Pick the primary filters for your product first, fix them server-side, and only expose the secondary filters as user-facing controls.