> ## Documentation Index
> Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Jobs Guide
> Learn how to effectively search for jobs using the Hirebase API
## Which search endpoint should I use?
Hirebase offers three job-search endpoints. Pick the right one based on the shape of your query:
| Endpoint | Use when | Filters work? |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`POST /v2/jobs/search`](/docs/api-reference/jobs/search-post) | You know what you're filtering on (titles, locations, salary, dates). | Structured filters are honored; note a few response fields (`score`, `expired`, `meta_targetability`) are not currently returned. |
| [`POST /v2/jobs/neural-search`](/docs/api-reference/jobs/neural-search-post) | You want semantic matching **plus** reliable filters. | Yes — hybrid vector + lexical. |
| [`POST /v2/jobs/vsearch`](/docs/api-reference/jobs/vsearch) | You have a natural-language query and don't need lexical filtering. | Core params only (`query`, `top_k`, `limit`, `page`, `accuracy`). Lexical filters are accepted but **not currently honored** — use Neural Search if you need them. |
If you're not sure: start with `POST /v2/jobs/search` for structured filters, or `POST /v2/jobs/neural-search` when you want to describe the role in natural language and still filter by things like experience, location, or industry.
## Structured Search (`POST /v2/jobs/search`)
Exact filters applied against parsed job fields. This is the right choice when your query is expressible as structured filters (titles, keywords, location, salary range, dates, experience, etc.).
### Search Parameters
* `job_titles`: Array of job titles to search for.
* `keywords`: Array of terms to match in job descriptions.
* `job_types`: Filter by job types (e.g., `"Full Time"`, `"Contract"`).
* `visa`: String `"true"` / `"false"` — filter for jobs that offer visa sponsorship.
* `location_group`: Predefined geographic area (e.g., `"Bay_Area"`). ⚠️ Not currently applied — use `geo_locations` instead.
* `location_types`: Work arrangements (`"Remote"`, `"Hybrid"`, `"In-Person"`).
* `geo_locations`: Array of location objects with `city`, `region`, and `country`. **(recommended for location filtering)**
* `geofilter_params`: Geographic proximity controls (`mode`, `radius`, `unit`).
* `experience`: Array of levels (`"Entry"`, `"Junior"`, `"Mid"`, `"Senior"`, `"Executive"`).
* `yoe`: Years of experience range with `min` / `max`.
* `salary`: Salary range with `min` / `max`.
* `currency`: ISO currency code (e.g., `"USD"`, `"GBP"`).
* `company_name`: Filter by specific company name.
* `industry`: Single industry or array of industries. See [List Industries](/docs/api-reference/data/get-industries). **(recommended for sector filtering)**
* `sub_industry`: Single subindustry or array. See [List Subindustries](/docs/api-reference/data/get-subindustries). ⚠️ Not currently applied — use `industry` instead.
* `company_types`: Headcount buckets (e.g., `"1-10"`, `"51-200"`). Use `types` for categorical labels like `"Startup"` or `"Enterprise"`.
* `sort_by`: `"relevance"`, `"date_posted"`, `"salary"`, `"company"`, or `"yoe"`.
* `sort_order`: `"asc"` or `"desc"`.
* `page`: Page number (1-indexed). Page 1 is free; page 2+ requires an API key.
* `limit`: Results per page (max 100).
### Example: Multi-parameter Search
```javascript theme={null}
const response = await fetch('https://api.hirebase.org/v2/jobs/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
body: JSON.stringify({
job_titles: ['Software Engineer', 'Backend Engineer'],
keywords: ['Python', 'AWS'],
location_types: ['Remote'],
experience: ['Mid'],
yoe: { min: 2, max: 5 },
salary: { min: 100000, max: 150000 },
sort_by: 'date_posted',
sort_order: 'desc',
page: 1,
limit: 10,
}),
});
const data = await response.json();
```
## Neural Search (`POST /v2/jobs/neural-search`)
Combines vector similarity with lexical filtering. Send a natural-language `query` under `vector` and add structured filters under `lexical`. This is the recommended endpoint for semantic search with reliable filtering.
```javascript theme={null}
const response = await fetch('https://api.hirebase.org/v2/jobs/neural-search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
body: JSON.stringify({
vector: {
query: 'senior backend engineer building distributed systems with Python and Kubernetes',
},
lexical: {
location_types: ['Remote', 'Hybrid'],
experience: ['Senior'],
industry: 'Tech, Software & IT Services',
days_ago: 30,
limit: 10,
},
}),
});
const data = await response.json();
```
## Vector Search (`POST /v2/jobs/vsearch`)
Pure semantic-similarity search. Use when you just want the closest matches to a natural-language query and don't need lexical filtering.
Vector search currently supports only the core search parameters (`search_type`, `query`, `top_k`, `accuracy`, `limit`, `page`). Lexical filter parameters are accepted but **do not currently narrow results**. For filtered semantic search, use [Neural Search](/docs/api-reference/jobs/neural-search-post).
```javascript theme={null}
const response = await fetch('https://api.hirebase.org/v2/jobs/vsearch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
body: JSON.stringify({
search_type: 'summary',
query: 'senior full-stack engineer with React, TypeScript, and AWS experience',
top_k: 10,
accuracy: 0.3,
limit: 10,
}),
});
const data = await response.json();
```
## Prompting Tips for Semantic Search
When writing queries for Neural Search or Vector Search:
1. **Use locations inline in the prompt:**
```javascript theme={null}
{
vector: { query: "Senior SWE based in Santa Clara, California" }
}
```
2. **Describe the kind of company:**
```javascript theme={null}
{
vector: {
query:
"Senior Director of Supply Chain Management in Pharmaceuticals, " +
"small manufacturing company with long-term aspirations to service a global economy."
}
}
```
3. **Spell out technical background:**
```javascript theme={null}
{
vector: {
query:
"5+ years of experience in quantitative analysis, preferably at large financial or " +
"technology firms. Expertise in machine learning frameworks such as PyTorch. Strong " +
"background in data analysis, statistical modeling, and programming. Located in " +
"New York City or willing to relocate. Ability to lead projects and mentor juniors."
}
}
```
**Be as precise as you want.** You have unlimited precision at your fingertips. Broad ("Medical Tech Sales") or niche ("L3 Product Manager used to working in fast-paced environments in small companies, looking to take the leap to a management role at a small consumer electronics company") both work.
**Find jobs you're qualified for.** Use your background to drive recommendations. Unlike plain text search which matches phrases, semantic search understands technical capability — searching `"Market Research"` also surfaces roles requiring related expertise like data analysis, competitive intelligence, or customer insights, even when those exact words don't appear.
**Provide context.** Mentioning "experience building with AWS" implies you're looking for Cloud Engineering work; "recent graduate" implies entry-level. Rich context gives the model more to match on.
**Prompting beats parameters for semantic search.** In our internal testing, a well-written `query` consistently outperforms structured filters passed to `vsearch`. Use Neural Search if you need both reliable filters **and** semantic matching.
## Next Steps
* Retrieve [detailed job information](/docs/api-reference/jobs/get-by-id) by ID.
* Explore [company data](/docs/guides/company-data) to enrich your results.