Search jobs

Authorization

AuthorizationBearer <token>

API key issued from the JobsPipe dashboard, prefixed jp_live_, sent as a bearer token in the Authorization header. Keys are read-only and scoped: jobs:read grants POST /v1/jobs/search, stack:read grants POST /v1/stack/scan. No scope grants write access to JobsPipe data.

In: header

Header Parameters

Idempotency-Key?string

Optional client-generated key (e.g. a UUID) that makes this POST safe to retry. A repeat with the same key returns the original response plus an Idempotent-Replayed: true header. Keys are retained for 24 hours.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Optional filters for the job search. All fields are optional and combine with AND. Array filters ending in _or match any of their values; those ending in _not exclude their values.

job_title_or?array<string>

Match jobs whose title contains any of these.

job_title_not?array<string>

Exclude jobs whose title contains any of these.

description_or?array<string>

Match jobs whose description contains any of these phrases.

description_not?array<string>

Exclude jobs whose description contains any of these phrases.

job_country_code_or?array<string>

Match any of these ISO alpha-2 country codes, e.g. US, GB.

job_country_code_not?array<string>

Exclude these ISO alpha-2 country codes.

job_location_or?array<string>

Match jobs whose city or region contains any of these, e.g. Seattle, WA. Combine with job_country_code_or to disambiguate same-named cities.

job_seniority_or?array<string>

Match any of these seniority levels.

include_unlabeled_seniority?boolean

Also return jobs whose seniority is unknown. About 55% of postings do not state a level, and job_seniority_or excludes every one of them by default.

skills_or?array<string>

Match jobs tagged with any of these skill slugs, e.g. python, kubernetes. Skills are extracted from title + description against a curated lexicon.

occupation_code_or?array<string>

ISCO-08 occupation codes. 4-digit codes match exactly (2512 = Software Developers); 1-3 digit codes match as hierarchy prefixes (25 = all ICT professionals).

isic_division_or?array<string>

ISIC Rev.4 industry divisions of the employer (2-digit, e.g. 62 = Computer programming and consultancy).

region_or?array<string>

US states and Canadian provinces as ISO 3166-2 codes, e.g. ["US-NY", "CA-ON"]. Qualified by country because the underlying column stores "CA" for California while "CA" is also Canada's country code. Matches every spelling a job board publishes, so "CA-ON" finds both "ON" and "Ontario".

employment_type_or?array<>

Match any of these employment types.

source_or?array<>

Return only jobs from any of these collector sources (OR): linkedin, indeed, ycombinator (aliases: yc, y combinator), workday, greenhouse, workable, smartrecruiters, ashby, lever, paylocity. To exclude sources instead, use source_not. An unrecognized source is not an error; it simply matches nothing, so the request returns zero jobs.

source_not?array<string>

Exclude jobs from these collector sources. Same accepted values and aliases as source_or, plus any source added later; an unrecognized source excludes nothing.

company_name_partial_match_or?array<string>

Match any of these company names (partial / contains).

min_employee_count?integer

Only jobs at companies with at least this many employees. Uses the exact headcount where known, otherwise the lower bound of the company's size band. Jobs whose company size is unknown are excluded.

max_employee_count?integer

Only jobs at companies with at most this many employees. Uses the EXACT headcount only -- a company known only by a band such as "10,000+" has no known upper bound and is excluded.

remote?boolean

true for remote-only, false to exclude remote.

work_arrangement_or?array<>

Match any of these work arrangements. Finer than remote, which answers false for hybrid and onsite alike. Jobs whose arrangement is unknown never match.

posted_at_max_age_days?integer

Only postings newer than this many days.

posted_at_gte?string

Only postings on or after this date (YYYY-MM-DD).

posted_at_lte?string

Only postings on or before this date (YYYY-MM-DD).

discovered_at_gte?string

Only postings first discovered by JobsPipe at or after this UTC datetime (YYYY-MM-DD HH:MM:SS). Tracks when we first saw the posting, not when it was posted; poll with your last run time to get only new jobs.

limit?integer

Maximum number of results to return, capped by your plan's page size: 25 on Free, 100 on Builder, 500 on Scale. One credit is one job returned, so this value is what the call costs: a response carrying 25 postings costs 25 credits. A search that matches nothing costs nothing.

include_total_results?boolean

Include the total match count in metadata.total_results.

blur_company_data?boolean

Preview mode. Employer name, domain, links and description are returned masked and has_blurred_data is true; job titles, locations, salary and all metadata counts stay in the clear. Consumes no credits, whatever the row count.

Response Body

`application/json`

curl -X POST "https://example.com/v1/jobs/search" \  -H "Content-Type: application/json" \  -d '{}'

{  "metadata": {    "total_results": 0,    "truncated_results": 0,    "total_companies": 0,    "truncated_companies": 0,    "next_cursor": "string"  },  "data": [    {      "id": "string",      "job_title": "string",      "normalized_title": "string",      "company": "string",      "company_domain": "string",      "company_object": {        "name": "string",        "domain": "string",        "url": "string",        "logo": "string",        "employee_count": 0,        "employee_count_min": 0,        "linkedin_url": "string",        "description": "string",        "location": {          "street": "string",          "city": "string",          "region": "string",          "postal_code": "string",          "country": "string"        }      },      "employer_type": "string",      "location": "string",      "short_location": "string",      "long_location": "string",      "country_code": "string",      "country": "string",      "countries": [        "string"      ],      "country_codes": [        "string"      ],      "continents": [        "string"      ],      "latitude": 0,      "longitude": 0,      "postal_code": "string",      "state_code": "string",      "cities": [        "string"      ],      "remote": true,      "hybrid": true,      "seniority": "string",      "employment_statuses": [        "string"      ],      "date_posted": "string",      "discovered_at": "2019-08-24T14:15:22Z",      "status": "string",      "closed_at": "string",      "closed_reason": "string",      "has_blurred_data": true,      "url": "string",      "source_url": "string",      "final_url": "string",      "salary_string": "string",      "salary_currency": "string",      "min_annual_salary": 0,      "max_annual_salary": 0,      "min_annual_salary_usd": 0,      "max_annual_salary_usd": 0,      "avg_annual_salary_usd": 0,      "keyword_slugs": [        "string"      ],      "technology_slugs": [        "string"      ],      "occupation_code": "string",      "occupation_label": "string",      "isic_division": "string",      "isic_division_label": "string",      "description": "string",      "easy_apply": true,      "hiring_team": [        null      ],      "reposted": true,      "date_reposted": "string",      "matching_phrases": [        "string"      ],      "matching_words": [        "string"      ],      "work_arrangement": "string",      "is_manager": true,      "job_function": "string",      "last_seen_at": "string",      "verified_at": "string",      "sources": [        {          "provider": "string",          "url": "string",          "seen_at": "2019-08-24T14:15:22Z"        }      ]    }  ]}

{  "error": "string",  "message": "string"}

{  "error": "string",  "message": "string"}

{  "error": "rate_limited",  "limit": 0,  "count": 0}

Authorization

Header Parameters

Request Body

Response Body

200application/json

401application/json

402application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`