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
}

POST

jobs

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

job_titles

string[]

Array of job titles to search for (matched against parsed job_title).

keywords

string[]

Array of keywords to match in job descriptions, techonologies, skills, and benefits

company_keywords

string[]

Array of keywords to match in company descriptions, services, and products

job_slug

string

Filter by the unique job slug (used for deep linking or targeting specific jobs).

location_types

string[]

Array of work arrangements. Accepted values: "Remote", "Hybrid", "In-Person".

location_group

string

Predefined geographic region used as a shortcut for common location groupings (e.g., "Bay_Area", "NYC_Metro").

geo_locations

object[]

Array of structured location objects with city, region, and country.

Show child attributes

city

string

City name

region

string

State, region, or province

country

string

Country name

geofilter_params

object

Geographic filtering configuration

Show child attributes

mode

string

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)

radius

number

Search radius for geographic filtering (defaults to 25.0)

unit

string

Units for radius; ‘mi’, ‘km’, ‘degrees’ (defaults to: ‘mi’)

experience

string[]

Array of experience levels. Accepted values: "Entry", "Junior", "Mid", "Senior", "Executive".

Any other value will return a 422 Unprocessable Entity error.

yoe

object

Years of experience range object

Show child attributes

min

number

Minimum years of experience

max

number

Maximum years of experience

job_types

string[]

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.

job_category

string[]

Filter by one or more job category tags (e.g., "Engineering Jobs", "Marketing Jobs"). See the full category list.

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.

job_board

string[]

Filter by the source job board (e.g., “iCIMS”, “Lever”, “Greenhouse”).

company_name

string

Filter by specific company name

company_slug

string

Filter by the unique company slug (used for deep linking or specific company targeting).

salary

object

Salary range object

Show child attributes

min

number

Minimum salary

max

number

Maximum salary

industry

string[]

Filter by industry sector. Can be a single string or an array of strings. See List Industries for accepted values.

sub_industry

string[]

Filter by more specific subindustry category. Can be a single string or an array of strings. See List Subindustries for accepted values.

days_ago

integer

How many days ago to filter for. Days Ago set to 3 will return jobs posted on and after 3 days ago.

date_posted

string

Filter by a specific posted date (format: YYYY-MM-DD). Returns jobs posted on or after this date.

month

string

Filter jobs posted in a specific month (format: YYYY-MM, e.g., "2026-03").

currency

string

Currency code to use when applying the salary filter (e.g., "USD", "EUR", "GBP").

visa

string

Filter for jobs that offer visa sponsorship ("true" or "false").

hide_recruiting_agencies

string

Filter out recruiter agency repostings ("true" or "false").

include_expired

string

Include expired job listings in the results ("true" or "false", default "false").

include_no_salary

string

Include jobs that do not specify a salary ("true" or "false") when a salary filter is applied.

include_yoe

string

Include jobs that do not specify years of experience ("true" or "false") when a yoe filter is applied.

hide_seen_jobs

string

Omit jobs the current user has already viewed ("true" or "false"). Requires user_id.

filter_incomplete_jobs

string

Filter out jobs with incomplete listing data ("true" or "false").

return_raw_description

string

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 when return_raw_description: "true") — full original HTML from the ATS.

sort_by

string

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_order

string

Sort direction ("asc" or "desc").

page

number

default:"1"

Page number for pagination

limit

number

default:"10"

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

jobs

array

Array of job objects

Show child attributes

_id

string

Unique identifier for the job

job_title

string

Title of the job

description

string

Full job description in HTML or plain text format

application_link

string

URL where candidates can apply for the job

job_categories

array

Categories or tags associated with the job posting (e.g., “Engineering”, “Design”)

job_type

string

Type of job, such as “Full Time”, “Part-time”, or “Contract”

location_type

string

Work arrangement, such as “Remote”, “Hybrid”, or “In-Person”

locations

array

Array of location objects

Show child attributes

city

string

Name of the city

region

string

Name of state or province

country

string

Name of the country

coordinates

object

Coordinates (long/lat) in GeoJSON format

bbox

number[]

Bounding Box (x1, y1, x2, y2) of the location region it encompasses

address

string

Normalized geographical address based on Nominatim API

salary_range

object|null

Salary range offered for the job. May be null if not specified

Show child attributes

min

number

Minimum salary

max

number

Maximum salary

currency

string

Currency code (e.g., USD, CAD)

period

string

Salary period (e.g., year, month)

yoe_range

object | null

Required years of experience. May be null when the listing does not specify a range.

Show child attributes

min

number

Minimum years of experience

max

number

Maximum years of experience

requirements_summary

string

Brief summary of key requirements or qualifications for the job

visa_sponsored

boolean

Indicates whether the job supports visa sponsorship

recruiter_agency

boolean

Indicates whether the listing was posted by a recruiting agency

skills

string[]

List of skills mentioned in the job description

team

string

Team at the company hiring for the position

technologies

string[]

List of technologies mentioned in the job description

benefits

string[]

List of benefits mentioned in the job description

education_level

string

Level of education required for the job

date_posted

string

The date when the job was posted. Format: YYYY-MM-DD

job_board

string

The name of the job board from which the listing was sourced (e.g., “iCIMS”)

language

string

Language the job posting is in

job_board_link

string

URL of the job board hosting the listing

job_slug

string

URL-friendly identifier for the job (used in deep-linking)

score

number

Relevance score for the job based on the search or ranking logic

experience_level

string

Parsed experience level for the role (e.g., "Entry", "Junior", "Mid", "Senior", "Executive").

description_raw

string

Full original HTML description from the ATS source. Only present when return_raw_description: "true" is set on the request.

expired

boolean

Whether the listing has been detected as expired/removed from the source job board.

contact_email

string | null

Contact email for the listing, when available. Paid users only.

contact_phone

string | null

Contact phone number for the listing, when available. Paid users only.

coolness_score

number

Company/role “coolness” rating (0–1).

flexibility_score

number

Work-flexibility rating (0–1) — remote/hybrid + work-life-balance signals.

compensation_value_score

number

Compensation competitiveness rating (0–1) vs role and geography.

benefits_score

number

Benefits package rating (0–1) based on listed benefits quality/quantity.

impact_autonomy_score

number

Role-level impact and autonomy rating (0–1).

prestige_score

number

Company/role prestige rating (0–1).

growth_score

number

Career growth / learning opportunity rating (0–1).

meta_completeness

number

Score (0–1) indicating how complete the parsed listing metadata is.

meta_targetability

number

Score (0–1) indicating how targetable/matchable the listing is for semantic search.

company_name

string

Name of the hiring company

company_slug

string

URL-friendly identifier for the company (used in deep-linking)

company_link

string

Official website of the company

company_logo

string

URL to the company’s logo image

company_data

object

Enriched company profile details

Show child attributes

description_summary

string

Short description about the company’s mission or services

linkedin_link

string | null

Link to the company’s LinkedIn profile

services

string[]

List of services that the company provides

size_range

object | null

Approximate number of employees

Show child attributes

min

number

Minimum number of employees

max

number

Maximum number of employees

industries

array

List of industries the company belongs to (e.g., “Design”, “Healthcare”)

subindustries

array

More specific categories under the industry (e.g., “Architecture”)

total_count

number

Total number of matching jobs for the query

company_count

number

Number of unique companies represented in the result set

page

number

Current page number in the response

limit

number

Number of job results returned per page

total_pages

number

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

Returns when the request contains invalid or improperly formatted data. Some possible reasons may include the following:

When the industry field is missing, not a string, or doesn’t match any value from the list of valid industries.
If sub_industry is not a valid string from the list of allowed sub-industries.
JSON decoding errors, such as malformed JSON or incorrect data types in the request body.

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.

Search Jobs (GET)

​Endpoint

​Request Body

​Response

​Example Request

​Error Responses

Endpoint

Request Body

Response

Example Request

Error Responses