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. Unknown fields are rejected with HTTP 400.

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 every word of any one of these phrases. Each phrase is split into words and matched case-insensitively; the words may appear in any order and need not be adjacent, so this is neither a substring nor an exact-phrase match.

description_not?array<string>

Exclude jobs whose description contains every word of any one of these phrases, matched the same way as description_or: case-insensitive, in any order, not necessarily adjacent.

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. Metro wrappers are stripped (Greater London also matches London) and a US state, Canadian province or UK nation by name matches every spelling of it (Pennsylvania also matches PA). Terms of three characters or fewer are codes or exact names and match whole values (WA is Washington state, never Iowa); a country code or name matches the whole country. Combine with job_country_code_or to disambiguate same-named cities. For a city by name, city_or is the precise filter.

city_or?array<string>

Whole city names, e.g. London, Munich. Case-insensitive, and a metro wrapper on the stored value is ignored (Greater London and London Area are London). Spellings and diacritics are normalised for cities we know: München finds Munich, Cracow finds Kraków. Other cities match the stored value exactly. Combine with job_country_code_or to disambiguate same-named cities; use job_location_or for substring matching.

job_seniority_or?array<string>

Match any of these seniority levels.

include_unlabeled_employment_type?boolean

Also return jobs whose employment type is unknown. About 27% of postings do not state one, and employment_type_or excludes every one of them by default.

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.

language_or?array<string>

Match postings WRITTEN in any of these languages, as lowercase ISO 639-1 codes, e.g. ["en"] or ["en", "sv"]. The language of the posting text, not of the country it sits in: 18.3% of Swedish postings and 17.7% of German ones are in English, and Canada is 84.5% English with the rest French. Use it to fetch only the roles a team can actually read when hiring across a multilingual market. Values that are not exactly two letters are ignored. Postings we have not labelled never match; add include_unknown: ["language"] to keep them.

language_not?array<string>

Exclude postings written in any of these languages, as lowercase ISO 639-1 codes, e.g. ["fr"]. Postings we have not labelled are kept, so this narrows by known language rather than requiring one.

source_or?array<string>

Return only jobs from any of these collector sources (OR). Job boards: linkedin, indeed, cvlibrary, resumelibrary, ycombinator, arbeitnow, himalayas, jobicy, themuse, remoteok, workingnomads, landingjobs, remotive, rise, bayt. Public employment services: eures, jobtech. ATS (company career sites): greenhouse, workday, ashby, lever, workable, recruitee, personio, smartrecruiters, breezy, paylocity, manatal, jobscore, teamtailor, pinpoint, hirehive. Case, spaces and punctuation are ignored ("CV-Library" = cvlibrary); aliases: yc for ycombinator, breezyhr for breezy. 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).

company_technology_slug_or?array<string>

Beta. Only jobs at companies whose own postings show they use any of these technologies (evidence tier likely or confirmed), e.g. ["snowflake", "dbt"]. At most 10 slugs. Answers 400 "filter not enabled" until the filter is switched on.

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 where known; a company known only by a size band matches when the band starts at or below this number ("11-50" matches 100, "10,000+" does not).

min_revenue_usd?number

Only jobs at companies whose estimated annual revenue, in US dollars, is at least this amount (the published revenue_usd). Companies with no revenue on record are excluded unless include_unknown contains "company_revenue".

max_revenue_usd?number

Only jobs at companies whose estimated annual revenue, in US dollars, is at most this amount (the published revenue_usd). Companies with no revenue on record are excluded unless include_unknown contains "company_revenue".

lei_or?array<>

Legal Entity Identifiers (ISO 17442). Matches jobs at a company with one of these LEIs or at any company in the corporate group the LEI heads. 1 to 50 LEIs of 20 letters and digits, e.g. ["5493001KJTIIGC8Y1R12"]; case is ignored, and a comma-separated string is accepted. Jobs at companies without a known LEI never match.

company_key_or?array<>

Company ids from the Companies endpoints (the key of a row of POST /v1/jobs/companies, or of a company profile). Matches only jobs at exactly these companies: unlike company_name_or, a name is never matched as a prefix, so Apple's id never brings in Apple Bank. 1 to 50 ids as strings of digits, e.g. ["14189461223778919517"]; a comma-separated string is accepted.

company_hq_country_or?array<>

Only jobs at companies headquartered in one of these countries, as ISO 3166-1 alpha-2 codes, e.g. ["US","DE"]. This is where the company is based, not where the job is: combine with job_country_code_or for "German companies hiring in the US". Case is ignored and a comma-separated string is accepted. Companies with no known headquarters never match.

company_hq_country_not?array<>

Only jobs at companies headquartered outside these countries (ISO 3166-1 alpha-2). Companies with no known headquarters never match.

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.

visa_sponsorship_or?array<>

Match any of these visa stances, parsed from the posting text: "offers" (sponsorship available), "no" (explicitly not available), "citizenship_required" (citizenship or security clearance required). Jobs that say nothing never match.

benefits_or?array<string>

Match jobs advertising any of these benefit slugs, e.g. ["401k", "health_insurance", "paid_time_off"] (any spelling: "health insurance" works too). Benefits come from structured board data (Indeed today), so coverage is partial; see metadata.field_coverage.

metro_code_or?array<string>

Match any of these US CBSA metro codes (e.g. "35620" New York). Resolved from the job's city/region; non-US jobs never match.

max_applicant_count?integer

Only jobs with at most this many applicants. Applicant counts exist only where the source exposes them (LinkedIn), so this filter also drops every job without a count.

has_recruiter_email?boolean

true for only jobs with a recruiter contact email parsed from the posting, false for only jobs without one.

min_salary_usd?integer

Only jobs whose posted salary reaches this annual USD amount (the max of the posted range, annualized). Jobs without a posted salary never match; estimated salaries are not consulted.

max_ghost_score?integer

Exclude jobs whose ghost-likelihood score (0-100) exceeds this. Unscored jobs always pass: the filter drops known-likely ghost jobs, it does not require a score.

include_unknown?array<>

Also match jobs whose value is UNKNOWN for these fields, e.g. ["seniority", "location"]. Without it every filter drops unknowns. "location" widens region_or within each subdivision's country, and job_location_or only when job_country_code_or is set. include_unknown_size, include_unlabeled_seniority and include_unlabeled_employment_type are aliases.

last_verified_max_age_days?integer

Only jobs seen on their source (or re-written) within this many days. Drops active jobs we have not confirmed recently.

esco_skill_id_or?array<string>

Match jobs tagged with any of these ESCO skill concept IDs (exact match). See each job's esco_skills for the id/label pairs.

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. Defaults to 25 and is capped by your plan's page size: 25 on Free, 100 below 300,000 credits a month, 500 from 300,000. One credit buys one job for the rest of the calendar month, so this value is the most the call can cost: a response carrying 25 postings the account has not had this month costs 25 credits, and postings it already paid for are free. A search that matches nothing costs nothing. metadata.credits_charged reports the actual cost.

offset?integer

Number of results to skip. Ignored when cursor is set. A positive offset takes precedence over page.

page?integer

Zero-based page index: skips page × limit results. Ignored when cursor is set or offset is positive.

cursor?|

Opaque pagination cursor. Pass metadata.next_cursor from the previous response to fetch the next page. Takes precedence over offset and page. null is treated as not set, and a cursor that cannot be decoded is ignored, so the first page is served.

order_by?array<>

Sort order. Results are always newest-first by posted date, and that is the only order accepted: [{"field":"posted_at","desc":true}]. date_posted is accepted as a synonym for posted_at, the field name is case-insensitive, and desc may be omitted. Any other field, "desc": false, or more than one sort key returns 400 rather than being silently ignored.

status?string

Lifecycle filter: active (still open), closed, or any. Defaults to active, and the default also applies to job_id_or and job_ids, so looking up a closed job by ID requires status "closed" or "any".

company_name_or?array<string>

Match any of these company names. Each name and the stored company name are normalized the same way: lowercased, punctuation replaced by spaces, whitespace collapsed, and one trailing legal suffix (such as Inc, LLC, Ltd, Corp, GmbH, PLC, Group or Holdings) dropped. A job matches when its normalized company name equals a normalized name or starts with it followed by a space, so Amazon matches Amazon Web Services but not Amazonia.

job_id_or?array<string>

Return jobs whose ID is any of these. Each value is matched against both the JobsPipe id and the source's native id. Behaves the same as job_ids; values from both are combined. The status filter still applies and defaults to active.

job_ids?array<string>

Look up these job IDs. Behaves the same as job_id_or: matched against the id or native id, combined with job_id_or, and subject to the status filter, which defaults to active.

include_unknown_size?boolean

Also return jobs at companies whose employee count is unknown when min_employee_count or max_employee_count is set; those filters otherwise exclude every unknown-size company. Alias of include_unknown: ["company_size"].

employer_type_or?array<>

Match only these employer types. "employer" hires for itself, "agency" is a staffing or recruitment firm posting for a client, "broker" is a job board republishing another company's listing. Including "employer" also returns jobs whose company has not been classified yet, which are served with employer_type "employer".

employer_type_not?array<>

Exclude these employer types. Only classified jobs are excluded: a job whose company has not been classified yet is served as "employer" but is never removed by this filter, so ["employer"] does not drop it and ["agency","broker"] keeps it.

include_total_results?boolean

Include the total match count in metadata.total_results.

include_technologies?boolean

Add technologies, the graded list of technologies each posting names, to every job. Off by default, and the field is then absent. Each returned job that names at least one technology costs 1 extra credit on top of the job's own credit, once per job per calendar month (UTC); jobs with none cost nothing extra. metadata.technologies_credits_charged reports that part of the cost.

blur_company_data?boolean

DEPRECATED and ignored. Preview mode has been removed: every search returns unmasked records and costs 1 credit per job not already paid for this month. Still accepted so existing integrations do not break, but it changes neither the response nor the price.

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",    "credits_charged": 0,    "jobs_already_paid": 0,    "technologies_credits_charged": 0,    "technologies_already_paid": 0,    "credits_remaining": 0,    "credits_allowance": 0,    "field_coverage": {      "property1": {        "field": "string",        "filled_pct": 0,        "by_source": {          "property1": 0,          "property2": 0        }      },      "property2": {        "field": "string",        "filled_pct": 0,        "by_source": {          "property1": 0,          "property2": 0        }      }    }  },  "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"        },        "founded": "string",        "intelligence": {          "revenue_usd": 0,          "revenue_year": 0,          "revenue_source": "string",          "revenue_confidence": "filed",          "entity_kind": "string",          "founded_year": 0,          "headcount": 0,          "industry": "string",          "hq_region": "string",          "hq_city": "string",          "revenue_low_usd": 0,          "revenue_high_usd": 0,          "headcount_low": 0,          "headcount_high": 0,          "lei": "string",          "legal_name": "string",          "group_lei": "string",          "group_name": "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,      "coordinates_source": "source",      "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"      ],      "technologies": [        {          "slug": "string",          "name": "string",          "kind": "string",          "category": "string",          "parent_category": "string",          "logo": "http://example.com",          "strength": "required",          "confidence": "high",          "sections": [            "string"          ],          "in_title": true,          "terms": [            "string"          ],          "terms_cs": [            "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"        }      ],      "work_arrangement_source": "string",      "visa_sponsorship": "string",      "benefits": [        "string"      ],      "salary_source": "string",      "salary_type": "string",      "estimated_min_annual_salary_usd": 0,      "estimated_avg_annual_salary_usd": 0,      "estimated_max_annual_salary_usd": 0,      "expires_at": "string",      "applicant_count": 0,      "recruiter_emails": [        "string"      ],      "listing_type": "string",      "metro_code": "string",      "metro_label": "string",      "normalized_city": "string",      "seniority_source": "string",      "esco_skills": [        {          "id": "string",          "label": "string"        }      ],      "ghost_score": 0,      "language": "string"    }  ]}

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

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

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

{  "error": "string"}

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

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

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

429application/json

502application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`