Skip to main content
POST
/
v2
/
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": {
    "vector.job_ids": [
      "<string>"
    ],
    "vector.artifact_id": "<string>",
    "vector.query": "<string>",
    "vector.vectors": [
      [
        123
      ]
    ]
  },
  "lexical": {
    "lexical.job_titles": [
      "<string>"
    ],
    "lexical.keywords": [
      "<string>"
    ],
    "lexical.job_slug": "<string>",
    "lexical.company_slug": "<string>",
    "lexical.location_group": "<string>",
    "lexical.location_types": [
      "<string>"
    ],
    "lexical.geo_locations": [
      {
        "lexical.geo_locations.city": "<string>",
        "lexical.geo_locations.region": "<string>",
        "lexical.geo_locations.country": "<string>"
      }
    ],
    "lexical.experience": [
      "<string>"
    ],
    "lexical.yoe": {
      "lexical.yoe.min": 123,
      "lexical.yoe.max": 123
    },
    "lexical.include_yoe": "<string>",
    "lexical.company_types": [
      "<string>"
    ],
    "lexical.company_name": "<string>",
    "lexical.date_posted": "<string>",
    "lexical.days_ago": 123,
    "lexical.month": "<string>",
    "lexical.salary": {
      "lexical.salary.min": 123,
      "lexical.salary.max": 123
    },
    "lexical.include_no_salary": "<string>",
    "lexical.currency": "<string>",
    "lexical.job_types": [
      "<string>"
    ],
    "lexical.job_category": [
      "<string>"
    ],
    "lexical.industry": [
      "<string>"
    ],
    "lexical.sub_industry": [
      "<string>"
    ],
    "lexical.visa": "<string>",
    "lexical.include_expired": "<string>",
    "lexical.hide_seen_jobs": "<string>",
    "lexical.user_id": "<string>",
    "lexical.job_board": [
      "<string>"
    ],
    "lexical.sort_by": "<string>",
    "lexical.sort_order": "<string>",
    "lexical.page": 123,
    "lexical.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
​
lexical
object
Traditional filtering parameters

​
Response

​
jobs
array
Array of job objects matching the query.
​
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

​
Example Request

{
  "vector": {
    "query": "machine learning engineer",
    "score_threshold": 0.8
  },
  "lexical": {
    "location_group": "Bay_Area",
    "experience": ["Mid", "Senior"],
    "yoe": {"min": 2, "max": 5},
    "job_types": ["Full-time"]
  },
  "page": 1,
  "limit": 5
}

​
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"}],
      "...": "..."
    }
  ],
  "total_count": 23,
  "page": 1,
  "limit": 5,
  "total_pages": 5
}

​
Error Responses

Returned when the request is malformed or contains invalid parameters.
Returned when an unexpected server-side error occurs.
Returned if you do not have access to this feature.