Jobs API
Reference Data API
Resume (Embeddings) API
Tasks API
Error Handling
Search Jobs
curl --request POST \
--url https://api.hirebase.org/v2/jobs/search \
--header 'Content-Type: application/json' \
--data '
{
"job_titles": [
"<string>"
],
"keywords": [
"<string>"
],
"company_keywords": [
"<string>"
],
"job_slug": "<string>",
"location_types": [
"<string>"
],
"location_group": "<string>",
"geo_locations": [
{
"city": "<string>",
"region": "<string>",
"country": "<string>"
}
],
"geofilter_params": {
"mode": "<string>",
"radius": 123,
"unit": "<string>"
},
"experience": [
"<string>"
],
"yoe": {
"min": 123,
"max": 123
},
"job_types": [
"<string>"
],
"job_category": [
"<string>"
],
"company_types": [
"<string>"
],
"job_board": [
"<string>"
],
"company_name": "<string>",
"company_slug": "<string>",
"salary": {
"min": 123,
"max": 123
},
"industry": [
"<string>"
],
"sub_industry": [
"<string>"
],
"days_ago": 123,
"date_posted": "<string>",
"month": "<string>",
"currency": "<string>",
"visa": "<string>",
"hide_recruiting_agencies": "<string>",
"include_expired": "<string>",
"include_no_salary": "<string>",
"include_yoe": "<string>",
"hide_seen_jobs": "<string>",
"filter_incomplete_jobs": "<string>",
"return_raw_description": "<string>",
"sort_by": "<string>",
"sort_order": "<string>",
"page": 123,
"limit": 123
}
'{
"jobs": [
{
"_id": "6814bw99fc2284gt4777f21a",
"company_name": "CompanyXYZ",
"job_title": "Site/Civil Engineer",
"description": "<p>CompanyXYZ is seeking a Site/Civil Project Engineer for our Richmond, Virginia office.</p>",
"application_link": "https://careers-companyxyz.icims.com/jobs/13876/site-civil-engineer/job",
"job_categories": ["Other"],
"job_type": "Full Time",
"location_type": "In-Person",
"yoe_range": {"min": 1, "max": 6},
"salary_range": null,
"date_posted": "2024-12-17",
"company_link": "https://www.companyxyz.com",
"company_logo": "https://c-1720-20210302-www-companyxyz-com.i.icims.com/images/default-source/site-assets/logos/companyxyz-logo.png",
"job_board": "iCIMS",
"job_board_link": "https://careers-companyxyz.icims.com",
"requirements_summary": "BS in Civil Engineering, 1-6 years of experience, PE in Virginia preferred",
"visa_sponsored": false,
"recruiter_agency": false,
"score": 13.449975967407227,
"company_data": {
"description_summary": "CompanyXYZ provides professional services, creating innovative solutions for built and natural environments nationwide.",
"linkedin_link": "https://www.linkedin.com/company/companyxyz",
"size_range": {"min": 1001, "max": 5000},
"industries": ["Design", "Construction"],
"subindustries": ["Architecture", "Building Construction"]
},
"company_slug": "companyxyz",
"job_slug": "site-civil-engineer-17",
"locations": [
{
"city": "Richmond",
"region": "Virginia",
"country": "United States"
}
]
}
],
"total_count": 1,
"company_count": 1,
"page": 1,
"limit": 10,
"total_pages": 1
}
Jobs API
Search Jobs
Search for jobs using traditional filtering methods
POST
/
v2
/
jobs
/
search
Search Jobs
curl --request POST \
--url https://api.hirebase.org/v2/jobs/search \
--header 'Content-Type: application/json' \
--data '
{
"job_titles": [
"<string>"
],
"keywords": [
"<string>"
],
"company_keywords": [
"<string>"
],
"job_slug": "<string>",
"location_types": [
"<string>"
],
"location_group": "<string>",
"geo_locations": [
{
"city": "<string>",
"region": "<string>",
"country": "<string>"
}
],
"geofilter_params": {
"mode": "<string>",
"radius": 123,
"unit": "<string>"
},
"experience": [
"<string>"
],
"yoe": {
"min": 123,
"max": 123
},
"job_types": [
"<string>"
],
"job_category": [
"<string>"
],
"company_types": [
"<string>"
],
"job_board": [
"<string>"
],
"company_name": "<string>",
"company_slug": "<string>",
"salary": {
"min": 123,
"max": 123
},
"industry": [
"<string>"
],
"sub_industry": [
"<string>"
],
"days_ago": 123,
"date_posted": "<string>",
"month": "<string>",
"currency": "<string>",
"visa": "<string>",
"hide_recruiting_agencies": "<string>",
"include_expired": "<string>",
"include_no_salary": "<string>",
"include_yoe": "<string>",
"hide_seen_jobs": "<string>",
"filter_incomplete_jobs": "<string>",
"return_raw_description": "<string>",
"sort_by": "<string>",
"sort_order": "<string>",
"page": 123,
"limit": 123
}
'{
"jobs": [
{
"_id": "6814bw99fc2284gt4777f21a",
"company_name": "CompanyXYZ",
"job_title": "Site/Civil Engineer",
"description": "<p>CompanyXYZ is seeking a Site/Civil Project Engineer for our Richmond, Virginia office.</p>",
"application_link": "https://careers-companyxyz.icims.com/jobs/13876/site-civil-engineer/job",
"job_categories": ["Other"],
"job_type": "Full Time",
"location_type": "In-Person",
"yoe_range": {"min": 1, "max": 6},
"salary_range": null,
"date_posted": "2024-12-17",
"company_link": "https://www.companyxyz.com",
"company_logo": "https://c-1720-20210302-www-companyxyz-com.i.icims.com/images/default-source/site-assets/logos/companyxyz-logo.png",
"job_board": "iCIMS",
"job_board_link": "https://careers-companyxyz.icims.com",
"requirements_summary": "BS in Civil Engineering, 1-6 years of experience, PE in Virginia preferred",
"visa_sponsored": false,
"recruiter_agency": false,
"score": 13.449975967407227,
"company_data": {
"description_summary": "CompanyXYZ provides professional services, creating innovative solutions for built and natural environments nationwide.",
"linkedin_link": "https://www.linkedin.com/company/companyxyz",
"size_range": {"min": 1001, "max": 5000},
"industries": ["Design", "Construction"],
"subindustries": ["Architecture", "Building Construction"]
},
"company_slug": "companyxyz",
"job_slug": "site-civil-engineer-17",
"locations": [
{
"city": "Richmond",
"region": "Virginia",
"country": "United States"
}
]
}
],
"total_count": 1,
"company_count": 1,
"page": 1,
"limit": 10,
"total_pages": 1
}
Search for jobs using common filters such as job titles, experience level, salary range, etc., in the JSON request body. The easiest way to start using our API is to use ourDocumentation Index
Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
Export button on our Search Page, this allows you to edit the tune the request using our Job Filters UI and easily export as a Javascript or cURL request.
Endpoint
POST /v2/jobs/search
Request Body
Use
job_types (plural) — job_type (singular) is silently ignored and your filter will not apply.Note:
- All request body fields are optional.
- Filter combinations can be mixed and matched.
- Use specific filters to narrow down search results and obtain relevant matches.
Array of job titles to search for (matched against parsed
job_title).Array of keywords to match in job descriptions, techonologies, skills, and benefits
Array of keywords to match in company descriptions, services, and products
Filter by the unique job slug (used for deep linking or targeting specific jobs).
Array of work arrangements. Accepted values:
"Remote", "Hybrid", "In-Person".Predefined geographic region used as a shortcut for common location groupings (e.g.,
"Bay_Area", "NYC_Metro").Geographic filtering configuration
Show child attributes
Show child attributes
Filtering mode for geographic search; ‘auto’, ‘weak’, ‘strict’, ‘box’ (defaults to: ‘auto’).
- Weak: uses coordinate based matching
- Strict: uses exact matching
- Box: uses bounding box matching
- Auto: uses heuristics to pick the optimal matching mechanism (recommended)
Search radius for geographic filtering (defaults to 25.0)
Units for radius; ‘mi’, ‘km’, ‘degrees’ (defaults to: ‘mi’)
Array of experience levels. Accepted values:
"Entry", "Junior", "Mid", "Senior", "Executive".Any other value will return a
422 Unprocessable Entity error.Array of job types (e.g.,
"Full Time", "Part Time", "Contract", "Internship").The correct field name is
job_types (plural). Using job_type (singular) is silently ignored — the request will succeed but the filter will not be applied.Filter by one or more job category tags (e.g.,
"Engineering Jobs", "Marketing Jobs"). See the full category list.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.Filter by the source job board (e.g., “iCIMS”, “Lever”, “Greenhouse”).
Filter by specific company name
Filter by the unique company slug (used for deep linking or specific company targeting).
Filter by industry sector. Can be a single string or an array of strings. See List Industries for accepted values.
Filter by more specific subindustry category. Can be a single string or an array of strings. See List Subindustries for accepted values.
How many days ago to filter for. Days Ago set to
3 will return jobs posted on and after 3 days ago.Filter by a specific posted date (format:
YYYY-MM-DD). Returns jobs posted on or after this date.Filter jobs posted in a specific month (format:
YYYY-MM, e.g., "2026-03").Currency code to use when applying the
salary filter (e.g., "USD", "EUR", "GBP").Filter for jobs that offer visa sponsorship (
"true" or "false").Filter out recruiter agency repostings (
"true" or "false").Include expired job listings in the results (
"true" or "false", default "false").Include jobs that do not specify a salary (
"true" or "false") when a salary filter is applied.Include jobs that do not specify years of experience (
"true" or "false") when a yoe filter is applied.Omit jobs the current user has already viewed (
"true" or "false"). Requires user_id.Filter out jobs with incomplete listing data (
"true" or "false").Set to
"true" to include the full original HTML description from the ATS source on each job object.Getting full job descriptions: By default, job results return a cleaned/summarized
description field (~900 chars). To get the full original HTML description from the ATS source, set return_raw_description to "true" — each job will then include a description_raw field with the complete HTML (~7,000+ chars typically).{
"job_titles": ["Software Engineer"],
"return_raw_description": "true",
"limit": 5
}
description(always present) — cleaned/summarized version.description_raw(only whenreturn_raw_description: "true") — full original HTML from the ATS.
Field to sort results by. Accepted values:
"relevance", "date_posted", "salary", "company", "yoe".Invalid values are silently ignored and the default sort (
relevance) is applied.Sort direction (
"asc" or "desc").Page number for pagination
Number of results per page
Note:The pagination (
page and limit) fields control the number of results returned and which subset of results is displayed.Response
Array of job objects
Show child attributes
Show child attributes
Unique identifier for the job
Title of the job
Full job description in HTML or plain text format
URL where candidates can apply for the job
Categories or tags associated with the job posting (e.g., “Engineering”, “Design”)
Type of job, such as “Full Time”, “Part-time”, or “Contract”
Work arrangement, such as “Remote”, “Hybrid”, or “In-Person”
Array of location objects
Show child attributes
Show child attributes
Name of the city
Name of state or province
Name of the country
Coordinates (long/lat) in GeoJSON format
Bounding Box (x1, y1, x2, y2) of the location region it encompasses
Normalized geographical address based on Nominatim API
Brief summary of key requirements or qualifications for the job
Indicates whether the job supports visa sponsorship
Indicates whether the listing was posted by a recruiting agency
List of skills mentioned in the job description
Team at the company hiring for the position
List of technologies mentioned in the job description
List of benefits mentioned in the job description
Level of education required for the job
The date when the job was posted. Format: YYYY-MM-DD
The name of the job board from which the listing was sourced (e.g., “iCIMS”)
Language the job posting is in
URL of the job board hosting the listing
URL-friendly identifier for the job (used in deep-linking)
Relevance score for the job based on the search or ranking logic
Parsed experience level for the role (e.g.,
"Entry", "Junior", "Mid", "Senior", "Executive").Full original HTML description from the ATS source. Only present when
return_raw_description: "true" is set on the request.Whether the listing has been detected as expired/removed from the source job board.
Contact email for the listing, when available. Paid users only.
Contact phone number for the listing, when available. Paid users only.
Company/role “coolness” rating (0–1).
Work-flexibility rating (0–1) — remote/hybrid + work-life-balance signals.
Compensation competitiveness rating (0–1) vs role and geography.
Benefits package rating (0–1) based on listed benefits quality/quantity.
Role-level impact and autonomy rating (0–1).
Company/role prestige rating (0–1).
Career growth / learning opportunity rating (0–1).
Score (0–1) indicating how complete the parsed listing metadata is.
Score (0–1) indicating how targetable/matchable the listing is for semantic search.
Name of the hiring company
URL-friendly identifier for the company (used in deep-linking)
Official website of the company
URL to the company’s logo image
Enriched company profile details
Show child attributes
Show child attributes
Short description about the company’s mission or services
Link to the company’s LinkedIn profile
List of services that the company provides
List of industries the company belongs to (e.g., “Design”, “Healthcare”)
More specific categories under the industry (e.g., “Architecture”)
Total number of matching jobs for the query
Number of unique companies represented in the result set
Current page number in the response
Number of job results returned per page
Total number of available pages for the query
Rate limit: 4 requests/second on search endpoints. Exceeding this limit returns a
429 Too Many Requests response. See Error Handling for best-practice retry logic.Example Request
curl -X POST https://api.hirebase.org/v2/jobs/search \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"job_titles": ["Software Engineer"],
"keywords": ["python", "backend"],
"location_types": ["In-Person", "Hybrid"],
"geo_locations": [
{"city": "New York", "region": "New York", "country": "United States"}
],
"geofilter_params": {"mode": "auto", "radius": 50, "unit": "mi"},
"experience": ["Mid", "Senior"],
"yoe": {"min": 2, "max": 8},
"job_types": ["Full Time"],
"salary": {"min": 100000, "max": 250000},
"currency": "USD",
"include_no_salary": "true",
"days_ago": 30,
"sort_by": "date_posted",
"sort_order": "desc",
"page": 1,
"limit": 10
}'
{
"jobs": [
{
"_id": "6814bw99fc2284gt4777f21a",
"company_name": "CompanyXYZ",
"job_title": "Site/Civil Engineer",
"description": "<p>CompanyXYZ is seeking a Site/Civil Project Engineer for our Richmond, Virginia office.</p>",
"application_link": "https://careers-companyxyz.icims.com/jobs/13876/site-civil-engineer/job",
"job_categories": ["Other"],
"job_type": "Full Time",
"location_type": "In-Person",
"yoe_range": {"min": 1, "max": 6},
"salary_range": null,
"date_posted": "2024-12-17",
"company_link": "https://www.companyxyz.com",
"company_logo": "https://c-1720-20210302-www-companyxyz-com.i.icims.com/images/default-source/site-assets/logos/companyxyz-logo.png",
"job_board": "iCIMS",
"job_board_link": "https://careers-companyxyz.icims.com",
"requirements_summary": "BS in Civil Engineering, 1-6 years of experience, PE in Virginia preferred",
"visa_sponsored": false,
"recruiter_agency": false,
"score": 13.449975967407227,
"company_data": {
"description_summary": "CompanyXYZ provides professional services, creating innovative solutions for built and natural environments nationwide.",
"linkedin_link": "https://www.linkedin.com/company/companyxyz",
"size_range": {"min": 1001, "max": 5000},
"industries": ["Design", "Construction"],
"subindustries": ["Architecture", "Building Construction"]
},
"company_slug": "companyxyz",
"job_slug": "site-civil-engineer-17",
"locations": [
{
"city": "Richmond",
"region": "Virginia",
"country": "United States"
}
]
}
],
"total_count": 1,
"company_count": 1,
"page": 1,
"limit": 10,
"total_pages": 1
}
Error Responses
422 Unprocessable Entity Error
422 Unprocessable Entity Error
Returns when the request contains invalid or improperly formatted data. Some possible reasons may include the following:
- When the
industryfield is missing, not a string, or doesn’t match any value from the list of valid industries. - If
sub_industryis not a valid string from the list of allowed sub-industries. JSONdecoding errors, such as malformed JSON or incorrect data types in the request body.
500 Internal Server Error
500 Internal Server Error
Returns when an unexpected error occurs on the server.
- Also occurs during unhandled server-side failures or bugs that prevent the request from being processed.
⌘I