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,
      "days_ago": 123,
      "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

https://api.hirebase.org

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,
      "days_ago": 123,
      "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

vector.job_ids

string[]

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

vector.artifact_id

string

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

vector.query

string

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

vector.vectors

number[][]

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

lexical

object

Traditional filtering parameters

Show child attributes

lexical.job_titles

string[]

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

lexical.keywords

string[]

Array of keywords to match within job descriptions.

lexical.job_slug

string

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

lexical.company_slug

string

Filter by a specific company’s slug.

lexical.location_group

string

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

lexical.location_types

string[]

Work arrangements to include (e.g., ["Remote","Hybrid","On-site"]).

lexical.geo_locations

object[]

Array of geographic filters.

Show child attributes

lexical.geo_locations.city

string

City name

lexical.geo_locations.region

string

State, region or province

lexical.geo_locations.country

string

Country name

lexical.experience

string[]

Experience level categories (e.g., ["Entry","Mid","Senior"]).

lexical.yoe

object

Years-of-experience range.

Show child attributes

lexical.yoe.min

number

Minimum years

lexical.yoe.max

number

Maximum years

lexical.include_yoe

string

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

lexical.company_types

string[]

Company size ranges (e.g., ["1-10","11-50","51-200"]).

lexical.company_name

string

Exact company name filter.

lexical.date_posted

string

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

lexical.days_ago

number

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

lexical.month

string

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

lexical.salary

object

Salary range filter.

Show child attributes

lexical.salary.min

number

Minimum salary

lexical.salary.max

number

Maximum salary

lexical.include_no_salary

string

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

lexical.currency

string

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

lexical.job_types

string[]

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

lexical.job_category

string[]

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

lexical.industry

string[]

Industries to filter by (e.g., ["Technology","Healthcare"]).

lexical.sub_industry

string[]

More specific industry categories.

lexical.visa

string

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

lexical.include_expired

string

Set to "true" to include expired listings.

lexical.hide_seen_jobs

string

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

lexical.user_id

string

User’s MongoDB ObjectId for personalized filtering.

lexical.job_board

string[]

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

lexical.sort_by

string

Field to sort lexical results by ("relevance", "date_posted", "salary", etc.).

lexical.sort_order

string

"asc" or "desc".

lexical.page

number

default:"1"

Page number

lexical.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

days_ago

int

Posting date (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

float

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

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

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.

Export Jobs Get Job by ID

⌘I

Jobs API

Companies 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

Resume (Embeddings) API

Tasks API

Error Handling

​Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Request Body

Response

Example Request

Example Response

Error Responses