Search Jobs Guide

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`	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`	You want semantic matching plus reliable filters.	Yes — hybrid vector + lexical.
`POST /v2/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 Information

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

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 & Compensation

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

company_name: Filter by specific company name.
industry: Single industry or array of industries. See List Industries. (recommended for sector filtering)
sub_industry: Single subindustry or array. See List 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".

Pagination & Sorting

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

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.

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.

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:

Use locations inline in the prompt:

{
  vector: { query: "Senior SWE based in Santa Clara, California" }
}

Describe the kind of company:

{
  vector: {
    query:
      "Senior Director of Supply Chain Management in Pharmaceuticals, " +
      "small manufacturing company with long-term aspirations to service a global economy."
  }
}

Spell out technical background:

{
  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 by ID.
Explore company data to enrich your results.

Getting Started

Guides

Which search endpoint should I use?

Structured Search (`POST /v2/jobs/search`)

Search Parameters

Example: Multi-parameter Search

Neural Search (`POST /v2/jobs/neural-search`)

Vector Search (`POST /v2/jobs/vsearch`)

Prompting Tips for Semantic Search

Next Steps

​Which search endpoint should I use?

​Structured Search (POST /v2/jobs/search)

​Search Parameters

​Example: Multi-parameter Search

​Neural Search (POST /v2/jobs/neural-search)

​Vector Search (POST /v2/jobs/vsearch)

​Prompting Tips for Semantic Search

​Next Steps

Which search endpoint should I use?

Structured Search (`POST /v2/jobs/search`)

Search Parameters

Example: Multi-parameter Search

Neural Search (`POST /v2/jobs/neural-search`)

Vector Search (`POST /v2/jobs/vsearch`)

Prompting Tips for Semantic Search

Next Steps