Skip to main content
POST
https://api.hirebase.org
/
v2
/
jobs
/
vsearch
Vector Search Jobs
curl --request POST \
  --url https://api.hirebase.org/v2/jobs/vsearch \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_type": "<string>",
  "query": "<string>",
  "job_id": "<string>",
  "artifact_id": "<string>",
  "industries": [
    "<string>"
  ],
  "subindustries": [
    "<string>"
  ],
  "job_title": "<string>",
  "job_type": [
    "<string>"
  ],
  "job_categories": [
    "<string>"
  ],
  "job_slug": "<string>",
  "job_board": [
    "<string>"
  ],
  "company_name": "<string>",
  "company_slug": "<string>",
  "locations": {
    "city": "<string>",
    "region": "<string>",
    "country": "<string>"
  },
  "date_posted": "<string>",
  "visa_sponsored": "<string>",
  "top_k": 123,
  "score": 123,
  "salary_from": 123,
  "salary_to": 123,
  "years_from": 123,
  "years_to": 123,
  "page": 123,
  "limit": 123,
  "offset": 123,
  "accuracy": "<string>"
}
'
{
  "jobs": [
    {
      "_id": "<string>",
      "company_name": "<string>",
      "job_title": "<string>",
      "description": "<string>",
      "application_link": "<string>",
      "job_categories": [
        "<string>"
      ],
      "job_type": "<string>",
      "salary_range": {
        "min": 123,
        "max": 123
      },
      "yoe_range": {
        "min": 123,
        "max": 123
      },
      "date_posted": "<string>",
      "company_link": "<string>",
      "company_logo": "<string>",
      "job_board": "<string>",
      "job_board_link": "<string>",
      "requirements_summary": "<string>",
      "visa_sponsored": true,
      "company_slug": "<string>",
      "job_slug": "<string>",
      "locations": {
        "city": "<string>",
        "region": "<string>",
        "country": "<string>"
      },
      "score": 123,
      "expired": {},
      "company_data": {
        "description_summary": "<string>",
        "linkedin_link": "<string>",
        "size_range": {
          "min": 123,
          "max": 123
        },
        "industries": [
          "<string>"
        ],
        "subindustries": [
          "<string>"
        ]
      }
    }
  ],
  "total_count": 123,
  "company_count": 123,
  "page": 123,
  "limit": 123,
  "total_pages": 123
}
Run semantic job searches using vector embeddings. Instead of relying on keyword matching, this API understands the meaning behind your query to return more relevant job results. You can use the Vector Search Jobs API to search by natural language, match jobs similar to a specific listing, or find jobs that align with a candidate’s resume.

​
Endpoint

POST /v2/jobs/vsearch

​
Search Types

Use the query parameter to search with a natural language description of the specific job.
Use the artifact_id parameter with search_type=resume to find jobs that match a resume.

​
Request Body

Note:
  • All request body fields are optional unless stated otherwise.
  • Begin with minimal filters to avoid excluding relevant results too early.
  • Filter combinations can be mixed and matched.
  • Use specific filters to narrow down search results and get relevant matches.
​
search_type
string
default:"summary"
required
Type of search to perform (“summary”, “job”, or “resume”)
​
query
string
required
Natural language description of the job you’re looking for
Note:Required only when the search type is Natural Language Query. Omit for Similar Job Search and Resume Matching search types.
​
job_id
string
required
The ID of the job to use as a reference for retrieving similar job listings
Note:Required only when the search type is Similar Job Search. Omit for Natural Language Query and Resume Matching search types.
​
artifact_id
string
required
Find jobs matching a resume or other document by its ID
Note:Required only when the search type is Resume Matching. Omit for Natural Language Query and Similar Job Search search types.
​
industries
string[]
Filter by one or more company industries (e.g., “Tech”, “Healthcare”).
​
subindustries
string[]
Filter by one or more specific subindustries.
​
job_title
string
Filter jobs by exact job title (e.g., “Software Engineer”, “Marketing Manager”).
​
job_type
string[]
Filter by employment type (e.g., “Full-time”, “Part-time”, “Contract”).
​
job_categories
string[]
Filter by one or more job category tags (e.g., “Engineering Jobs”, “Marketing”).
​
job_slug
string
Filter by the unique slug of a job (used to fetch or highlight a specific job).
​
job_board
string[]
Filter by the job board source (e.g., “Workable”, “Greenhouse”).
​
company_name
string
Filter by the name of the company offering the job.
​
company_slug
string
Filter jobs by the unique company slug identifier.
​
locations
object
Filter jobs by one or more locations. Each location object can include city, region, or country.
​
date_posted
string
Filter jobs posted on or after a specific date (format: YYYY-MM-DD).
​
visa_sponsored
string
Filter to include only jobs that offer visa sponsorship.
​
top_k
number
default:"10"
Number of results to return
​
score
float
Minimum similarity score to include in results
Note:Higher similarity scores indicate stronger semantic matches.
​
salary_from
number
Minimum salary filter
​
salary_to
number
Maximum salary filter
​
years_from
number
Minimum years of experience filter
​
years_to
number
Maximum years of experience filter
​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"10"
Number of results per page
​
offset
number
Offset for results (alternative to page)
Note:The page, limit, and offset fields all control how results are paginated i.e., how many results you get and which ones are returned. You can use either page and limit together or use offset withlimit.
  • If you’re using page, you’re asking for a specific page of results (like page 2 or page 3), and limit defines how many results appear on each page.
  • If you’re using offset, you’re skipping a certain number of results before starting to return data. For example, offset= 20 with limit= 10 means “skip the first 20 results, then return the next 10.”
​
accuracy
string
default:"medium"
Search accuracy level (“low”, “medium”, “high”) - higher accuracy takes more time

​
Response

​
jobs
array
Array of job objects, each representing a single job listing along with company and scoring metadata.
​
total_count
number
Total number of matching job listings across all pages.
​
company_count
number
Total number of unique companies represented in the current job results.
​
page
number
Current page number of the response.
​
limit
number
Maximum number of jobs returned per page.
​
total_pages
number
Total number of pages available for the current query.

​
Example Request

curl -X POST "https://api.hirebase.org/v2/jobs/vsearch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "search_type": "summary",
    "query": "Senior backend engineer with Python and microservices experience",
    "salary_from": 120000,
    "top_k": 15
  }'

​
Example Response

{
"jobs": [
        {
            "_id": "51e870e407b47818y9c16f55",
            "company_name": "CompanyXYZ",
            "job_title": "Senior Backend Engineer (Python)",
            "description": "<p>We are seeking a highly skilled and experienced Senior Backend Engineer proficient in Python to join our dynamic and innovative engineering team.</p><h2>Requirements</h2><ul><li>Bachelor’s or higher degree in Computer Science, Software Engineering, or a related field.</li><li>Minimum of 3 years of proven experience as a Backend Engineer with expertise in Python development.</li><li>Demonstrated ability to design and implement scalable and maintainable systems.</li><li>Excellent problem-solving and debugging skills.</li><li>Effective communication and collaboration skills.</li></ul><h2>Benefits</h2><ul><li>Be part of a dynamic team that values innovation and fosters creativity.</li><li>Work on projects that contribute to shaping the future of the encryption market.</li><li>Opportunity for growth and skill development within a forward-thinking company.</li><li>Competitive salary and benefits package.</li></ul>",
            "application_link": "https://jobs.workable.com/view/kEaoFLFZs317RE9B8cZLtj/senior-backend-engineer-(python)-in-bulverde-at-companyxyz",
            "job_categories": [
                "Engineering Jobs"
            ],
            "job_type": "Full-time",
            "location_type": "In-Person",
            "yoe_range": {
                "min": 3,
                "max": 3
            },
            "salary_range": null,
            "date_posted": "2023-12-07",
            "company_link": "https://www.companyxyz.com/",
            "company_logo": "https://workablehr.s3.amazonaws.com/uploads/account/logo/535455/logo",
            "job_board": "Workable",
            "job_board_link": "https://jobs.workable.com/company/mkC1FVMudAyt2jHWgCqc9z/jobs-at-companyxyz",
            "requirements_summary": "3+ years of experience, Bachelor's degree, expertise in Python and system design",
            "visa_sponsored": false,
            "company_data": {
                "description_summary": "CompanyXYZ is a global leader in secure and compliant data encryption hardware and solutions.",
                "linkedin_link": "https://www.linkedin.com/company/companyxyz",
                "size_range": {
                    "min": 51,
                    "max": 200
                },
                "industries": [
                    "Tech, Software & IT Services"
                ],
                "subindustries": [
                    "Hardware & Equipment",
                    "Data Management & Analytics"
                ]
            },
            "company_slug": "companyxyz",
            "job_slug": "senior-backend-engineer-python-15",
            "locations": [
                {
                    "city": "Bulverde",
                    "region": "Texas",
                    "country": "United States"
                }
            ],
            "score": 0.6700418591499329
        },
 ],
    "total_count": 100,
    "company_count": 0,
    "page": 1,
    "limit": 10,
    "total_pages": 10
}

​
Error Responses

Returns when the request is missing required data or includes invalid parameters.
  • For example, this error occurs if an artifact_id is provided but not found in the system.
Returns when the API key is missing, invalid, or incorrect.
Returns when your account does not have permission to access the requested feature.
  • This usually means the feature is restricted to certain subscription tiers.
Best Practices
  • Use detailed natural language queries: The API performs best when queries are specific and clearly describe experience, goals, or desired roles.
  • Prefer prompts over structured parameters: The most accurate matches come from descriptive prompts rather than strict filters.