Vector Search Jobs

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

Natural Language Query

Use the query parameter to search with a natural language description of the specific job.

Similar Job Search

Use the job_id parameter with search_type=job to find jobs similar to a specific job.

Resume Matching

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.

Show child attributes

city

string

City name to filter jobs by (e.g., “New York”, “Berlin”).

region

string

State, province, or region name (e.g., “California”, “Bavaria”).

country

string

Country name or code (e.g., “United States”, “DE”).

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.

Show child attributes

_id

string

Unique identifier for the job posting

company_name

string

Name of the company offering the job

job_title

string

Title of the job role

description

string

Full HTML-formatted description of the job posting

application_link

string

Direct URL to apply for the job

job_categories

string[]

List of job category tags used for classification (e.g., “Engineering Jobs”)

job_type

string

Type of job based on employment structure (e.g., “Full-time”, “Part-time”)

salary_range

object | null

Estimated or provided salary range. May be null if unspecified

Show child attributes

min

number

Minimum salary (if available)

max

number

Maximum salary (if available)

yoe_range

object

Range of required years of experience.

Show child attributes

min

number

Minimum years of experience

max

number

Maximum years of experience

date_posted

string

Date the job was posted, in YYYY-MM-DD format

company_link

string

Link to the official website of the company

company_logo

string

URL of the company’s logo image

job_board

string

Name of the job board where the job was sourced (e.g., “Workable”, “Greenhouse”)

job_board_link

string

Link to the job board’s listing page for this company

requirements_summary

string

Brief summary of key job requirements, such as qualifications and skills

visa_sponsored

boolean

Indicates whether the company offers visa sponsorship for this role

company_slug

string

Unique slug used to identify the company programmatically

job_slug

string

Unique slug used to identify the job posting programmatically

locations

object

List of job location objects

Show child attributes

city

string

City where the job is based

region

string

Region or state of the job location

country

string

Country of the job location

score

float

Similarity or relevance score for this job (range: 0.0 to 1.0)

expired

boolean (optional)

Indicates whether the job listing is expired. May be missing if not applicable

company_data

object

Enriched company information related to the job

Show child attributes

description_summary

string

Short summary of the company’s mission or business focus

linkedin_link

string

Link to the company’s LinkedIn profile.

size_range

object

Employee size range at the company

Show child attributes

min

number

Minimum number of employees.

max

number

Maximum number of employees.

industries

string[]

Primary industries the company operates in (e.g., “Tech, Software & IT Services”)

subindustries

string[]

More specific subindustry classifications under the primary industries

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

400 Bad Request

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.

401 Unauthorized

Returns when the API key is missing, invalid, or incorrect.

403 Forbidden

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.

Jobs API

Companies API

Resume (Embeddings) API

Tasks API

Error Handling

Endpoint

Search Types

Request Body

Response

Example Request

Example Response

Error Responses

Jobs API

Companies API

Resume (Embeddings) API

Tasks API

Error Handling

​Endpoint

​Search Types

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Search Types

Request Body

Response

Example Request

Example Response

Error Responses