Neural Search Jobs

curl --request POST \
  --url https://api.hirebase.org/v2/jobs/neural-search \
  --header 'Content-Type: application/json' \
  --data '
{
  "vector": {
    "job_ids": [
      "<string>"
    ],
    "artifact_id": "<string>",
    "query": "<string>",
    "vectors": [
      [
        123
      ]
    ]
  },
  "lexical": {
    "job_titles": [
      "<string>"
    ],
    "keywords": [
      "<string>"
    ],
    "job_slug": "<string>",
    "company_slug": "<string>",
    "location_group": "<string>",
    "location_types": [
      "<string>"
    ],
    "geo_locations": [
      {
        "city": "<string>",
        "region": "<string>",
        "country": "<string>"
      }
    ],
    "experience": [
      "<string>"
    ],
    "yoe": {
      "min": 123,
      "max": 123
    },
    "include_yoe": "<string>",
    "company_types": [
      "<string>"
    ],
    "company_name": "<string>",
    "date_posted": "<string>",
    "days_ago": 123,
    "month": "<string>",
    "salary": {
      "min": 123,
      "max": 123
    },
    "include_no_salary": "<string>",
    "currency": "<string>",
    "job_types": [
      "<string>"
    ],
    "job_category": [
      "<string>"
    ],
    "industry": "<string>",
    "sub_industry": [
      "<string>"
    ],
    "visa": "<string>",
    "include_expired": "<string>",
    "hide_seen_jobs": "<string>",
    "user_id": "<string>",
    "job_board": [
      "<string>"
    ],
    "sort_by": "<string>",
    "sort_order": "<string>",
    "page": 123,
    "limit": 123
  }
}
'

{
  "jobs": [
    {
      "_id": "<string>",
      "job_title": "<string>",
      "description": "<string>",
      "application_link": "<string>",
      "job_categories": [
        {}
      ],
      "job_type": "<string>",
      "location_type": "<string>",
      "locations": [
        {
          "city": "<string>",
          "region": "<string>",
          "country": "<string>"
        }
      ],
      "salary_range": {
        "min": 123,
        "max": 123,
        "currency": "<string>",
        "period": "<string>"
      },
      "yoe_range": {
        "min": 123,
        "max": 123
      },
      "requirements_summary": "<string>",
      "visa_sponsored": true,
      "date_posted": "<string>",
      "job_board": "<string>",
      "job_board_link": "<string>",
      "job_slug": "<string>",
      "company_name": "<string>",
      "company_slug": "<string>",
      "company_link": "<string>",
      "company_logo": "<string>",
      "company_data": {
        "description_summary": "<string>",
        "linkedin_link": {},
        "size_range": {
          "min": 123,
          "max": 123
        },
        "industries": [
          {}
        ],
        "subindustries": [
          {}
        ]
      },
      "vector_score": 123
    }
  ],
  "total_count": 123,
  "page": 123,
  "limit": 123,
  "total_pages": 123
}

POST

jobs

neural-search

Neural Search Jobs

curl --request POST \
  --url https://api.hirebase.org/v2/jobs/neural-search \
  --header 'Content-Type: application/json' \
  --data '
{
  "vector": {
    "job_ids": [
      "<string>"
    ],
    "artifact_id": "<string>",
    "query": "<string>",
    "vectors": [
      [
        123
      ]
    ]
  },
  "lexical": {
    "job_titles": [
      "<string>"
    ],
    "keywords": [
      "<string>"
    ],
    "job_slug": "<string>",
    "company_slug": "<string>",
    "location_group": "<string>",
    "location_types": [
      "<string>"
    ],
    "geo_locations": [
      {
        "city": "<string>",
        "region": "<string>",
        "country": "<string>"
      }
    ],
    "experience": [
      "<string>"
    ],
    "yoe": {
      "min": 123,
      "max": 123
    },
    "include_yoe": "<string>",
    "company_types": [
      "<string>"
    ],
    "company_name": "<string>",
    "date_posted": "<string>",
    "days_ago": 123,
    "month": "<string>",
    "salary": {
      "min": 123,
      "max": 123
    },
    "include_no_salary": "<string>",
    "currency": "<string>",
    "job_types": [
      "<string>"
    ],
    "job_category": [
      "<string>"
    ],
    "industry": "<string>",
    "sub_industry": [
      "<string>"
    ],
    "visa": "<string>",
    "include_expired": "<string>",
    "hide_seen_jobs": "<string>",
    "user_id": "<string>",
    "job_board": [
      "<string>"
    ],
    "sort_by": "<string>",
    "sort_order": "<string>",
    "page": 123,
    "limit": 123
  }
}
'

{
  "jobs": [
    {
      "_id": "<string>",
      "job_title": "<string>",
      "description": "<string>",
      "application_link": "<string>",
      "job_categories": [
        {}
      ],
      "job_type": "<string>",
      "location_type": "<string>",
      "locations": [
        {
          "city": "<string>",
          "region": "<string>",
          "country": "<string>"
        }
      ],
      "salary_range": {
        "min": 123,
        "max": 123,
        "currency": "<string>",
        "period": "<string>"
      },
      "yoe_range": {
        "min": 123,
        "max": 123
      },
      "requirements_summary": "<string>",
      "visa_sponsored": true,
      "date_posted": "<string>",
      "job_board": "<string>",
      "job_board_link": "<string>",
      "job_slug": "<string>",
      "company_name": "<string>",
      "company_slug": "<string>",
      "company_link": "<string>",
      "company_logo": "<string>",
      "company_data": {
        "description_summary": "<string>",
        "linkedin_link": {},
        "size_range": {
          "min": 123,
          "max": 123
        },
        "industries": [
          {}
        ],
        "subindustries": [
          {}
        ]
      },
      "vector_score": 123
    }
  ],
  "total_count": 123,
  "page": 123,
  "limit": 123,
  "total_pages": 123
}

This endpoint enables you to perform hybrid searches: apply familiar filters (titles, locations, salary, etc.) while simultaneously ranking results by vector similarity to a text query or embedding.

Endpoint

POST /v2/jobs/neural-search

Request Body

Note:

You can supply only vector, only lexical, or both; at least one must be present.
If you include both, results are ordered by combined ranking (semantic score then lexical rank).

vector

object

Parameters for semantic, embedding-based search

Show child attributes

job_ids

string[]

Optional list of explicit job IDs to constrain the semantic search.

artifact_id

string

ID of the embedding artifact (e.g., resume) to use.

query

string

Semantic text query to be encoded into a vector for similarity matching.

vectors

number[][]

Explicit embedding vectors (each must be 768 elements long) to compare against job vectors.

lexical

object

Traditional filtering parameters

Show child attributes

job_titles

string[]

Array of job titles to search for (e.g., ["Software Engineer", "Data Scientist"]).

keywords

string[]

Array of keywords to match within job descriptions.

job_slug

string

Filter by a specific job’s slug (deep-link identifier).

company_slug

string

Filter by a specific company’s slug.

location_group

string

Predefined location set (e.g., "Bay_Area").

location_types

string[]

Work arrangements to include. Accepted values: "Remote", "Hybrid", "In-Person".

geo_locations

object[]

Array of geographic filters.

Show child attributes

city

string

City name

region

string

State, region or province

country

string

Country name

experience

string[]

Experience level categories. Accepted values: "Entry", "Junior", "Mid", "Senior", "Executive".

yoe

object

Years-of-experience range.

Show child attributes

min

number

Minimum years

max

number

Maximum years

include_yoe

string

Set to "true" to include jobs without specified years of experience.

company_types

string[]

Filter jobs by the hiring company’s headcount bucket. Accepted values: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10000+". Pass multiple values to combine ranges (e.g., ["11-50", "51-200"]).

This parameter is named company_types for historical reasons but currently filters by company size. A separate classification filter (Public Company / Non-Profit / etc.) will be added in a future API update.

company_name

string

Exact company name filter.

date_posted

string

Relative timeframe (e.g., "today", "last_week", "last_month").

days_ago

number

Jobs posted in the last n days (e.g., 7).

month

string

Specific month in YYYY-MM format (e.g., "2023-12").

salary

object

Salary range filter.

Show child attributes

min

number

Minimum salary

max

number

Maximum salary

include_no_salary

string

Set to "true" to include listings without salary data.

currency

string

Three-letter currency code (e.g., "USD").

job_types

string[]

Employment types (e.g., ["Full Time","Contract","Internship"]).

job_category

string[]

Specific job categories (e.g., ["Data Science"]).

industry

string

Industry to filter by (e.g., "Tech, Software & IT Services", "Healthcare").

industry must be a single string, not an array. Passing an array may result in a 500 error.

sub_industry

string[]

More specific industry categories.

visa

string

Set to "true" to only include visa-sponsored roles.

include_expired

string

Set to "true" to include expired listings.

hide_seen_jobs

string

Set to "true" to omit jobs the user has already viewed.

user_id

string

User’s MongoDB ObjectId for personalized filtering.

job_board

string[]

Source job boards (e.g., ["iCIMS","Greenhouse"]).

sort_by

string

Field to sort lexical results by. Accepted values: "relevance", "date_posted", "salary", "company", "yoe". Invalid values are silently ignored.

sort_order

string

"asc" or "desc".

page

number

default:"1"

Page number

limit

number

default:"10"

Results per page

Response

jobs

array

Array of job objects matching the query.

Show child attributes

_id

string

Unique job identifier

job_title

string

Job title

description

string

Full job description (HTML or text)

application_link

string

URL to apply

job_categories

array

Tags/categories for the role

job_type

string

Employment type

location_type

string

Work arrangement

locations

array

Array of location objects

Show child attributes

city

string

City name

region

string

State or province

country

string

Country

salary_range

object|null

Offered salary range

Show child attributes

min

number

Minimum salary

max

number

Maximum salary

currency

string

Currency code

period

string

Period (year, month)

yoe_range

object

Required years of experience

Show child attributes

min

number

Min years

max

number

Max years

requirements_summary

string

Brief qualifications summary

visa_sponsored

boolean

Whether visa sponsorship is offered

date_posted

string

Posting date (format: YYYY-MM-DD).

job_board

string

Source job board

job_board_link

string

URL of the job board

job_slug

string

Deep-link slug for the job

company_name

string

Name of hiring company

company_slug

string

Company slug

company_link

string

Company website

company_logo

string

URL to company logo

company_data

object

Enriched company profile

Show child attributes

description_summary

string

Short company description

linkedin_link

string|null

LinkedIn URL

size_range

object|null

Employee count range

Show child attributes

min

number

Min headcount

max

number

Max headcount

industries

array

Industry sectors

subindustries

array

Detailed industry categories

vector_score

number

Semantic similarity score (0.0–1.0) from vector matching

total_count

number

Total number of matching jobs

page

number

Current page number

limit

number

Number of results returned

total_pages

number

Total pages available

Rate limit: 4 requests/second on search endpoints. See Error Handling.

Example Request

curl -X POST https://api.hirebase.org/v2/jobs/neural-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "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
    }
  }'

Example Response

{
  "jobs": [
    {
      "_id": "6814bw99fc2284gt4777f21a",
      "job_title": "Machine Learning Engineer",
      "company_name": "AI Innovations",
      "vector_score": 0.87,
      "date_posted": "2025-07-15",
      "location_type": "Hybrid",
      "locations": [{"city":"San Francisco","region":"CA","country":"United States"}],
      "job_type": "Full Time",
      "salary_range": { "min": 180000, "max": 240000 },
      "currency": "USD",
      "experience_level": "Senior",
      "vector_score": 0.87
    }
  ],
  "total_count": 23,
  "page": 1,
  "limit": 5,
  "total_pages": 5
}

Error Responses

422 Unprocessable Entity

Returned when the request is malformed or contains invalid parameters.

500 Internal Server Error

Returned when an unexpected server-side error occurs.

403 Forbidden

Returned if you do not have access to this feature.

Search Jobs (GET)

Vector Search Jobs

Jobs API

Companies API

Reference Data API

Resume (Embeddings) API

Tasks API

Error Handling

Neural Search Jobs

Endpoint

Request Body

Response

Example Request

Example Response

Error Responses

Jobs API

Companies API

Reference Data API

Resume (Embeddings) API

Tasks API

Error Handling

Documentation Index

​Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Request Body

Response

Example Request

Example Response

Error Responses