{ "openapi": "3.1.0", "info": { "title": "JobsPipe Account API", "version": "1.0.0", "description": "The calling account and its credits, feedback on the data, and checkout for packages and credits.", "contact": { "name": "JobsPipe", "url": "https://jobspipe.dev", "email": "support@jobspipe.dev" } }, "x-service-info": { "categories": [ "data", "jobs", "technographics" ], "docs": { "homepage": "https://jobspipe.dev", "apiReference": "https://docs.jobspipe.dev", "llms": "https://jobspipe.dev/llms.txt" } }, "servers": [ { "url": "https://api.jobspipe.dev" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "summary": "Get the account behind this credential", "x-consequence": "read-only", "x-side-effects": "none - consumes no credits", "security": [ { "apiKey": [] }, { "oidc": [ "jobs:read" ] } ], "description": "Returns who the API key or OAuth token belongs to, the plan it is on and this calendar month's credit usage. Costs no credits and does not count against the per-second rate limit, so call it before a large search to check what is left.", "responses": { "200": { "description": "The connected account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "auth_type": { "type": "string", "description": "How the request was authenticated: api_key, oauth or session." }, "plan": { "type": "string", "description": "A plan name, or credits:N for N thousand credits a month." }, "month": { "type": "string", "description": "The calendar month the usage figures cover, YYYY-MM in UTC." }, "monthly_credits": { "type": "integer" }, "credits_used": { "type": "integer" }, "credits_remaining": { "type": "integer" }, "extra_credits": { "type": "integer", "description": "One-time credits bought on top of the plan, drawn after the monthly allowance." }, "max_results_per_request": { "type": "integer" }, "requests_per_second": { "type": "number" } } }, "example": { "user_id": "usr_8f2c1d", "email": "dev@example.com", "name": "Ada Developer", "auth_type": "api_key", "plan": "builder", "month": "2026-10", "monthly_credits": 10000, "credits_used": 126, "credits_remaining": 9874, "extra_credits": 0, "max_results_per_request": 100, "requests_per_second": 5 } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Account" ] } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "summary": "Tell JobsPipe what was wrong or missing", "x-consequence": "stores a report for a person to read", "x-side-effects": "none - consumes no credits and takes no rate-limit slot", "security": [ { "apiKey": [] }, { "oidc": [ "jobs:read" ] } ], "description": "Send a report about the data or the tools: a posting that is closed or stale, a wrong field, a search that missed what exists, thin coverage, a confusing tool or answer, or pricing. A person reads every submission. Costs no credits and does not count against the search rate limit; up to 10 a minute and 100 a day per account. Include job_ids and the exact query so the report can be reproduced.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "category", "message" ], "properties": { "category": { "type": "string", "enum": [ "data_quality", "missing_data", "search_results", "tool_usability", "pricing", "other" ], "description": "data_quality: a posting or field is wrong or stale. missing_data: something that should exist does not. search_results: a search missed or misranked. tool_usability: a tool or answer was confusing. pricing: credits or plans. other: anything else." }, "message": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What was wrong, missing or confusing, in the sender's own words." }, "job_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 50, "description": "The postings the report is about, by the id a search or fetch returned." }, "tool": { "type": "string", "maxLength": 64, "description": "The tool or endpoint that was being used." }, "query": { "type": "object", "additionalProperties": true, "description": "The exact search input that was run, as given, so a miss can be replayed. At most 8 KB as JSON." }, "agent": { "type": "string", "maxLength": 128, "description": "The client or model sending the report." } } }, "example": { "category": "data_quality", "message": "This posting is closed on the company's site.", "job_ids": [ "4450909183" ] } } } }, "responses": { "201": { "description": "Received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "received_at": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } }, "example": { "id": "5d1f0c7e-2b8a-4c3e-9f61-0a7d3e2b9c48", "received_at": "2026-10-25T10:00:00.000Z", "note": "Thanks. A person reads every report." } } } }, "400": { "description": "Invalid request: an unknown category, an empty or too long message, or an unknown key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "More than 10 submissions a minute or 100 a day; Retry-After says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Account" ] } }, "/v1/billing/checkout": { "post": { "operationId": "createBillingCheckout", "summary": "Start a package purchase", "x-consequence": "creates a Stripe Checkout or billing-portal link for the account holder", "x-side-effects": "none until the account holder pays - the call itself charges nothing and consumes no credits", "security": [ { "apiKey": [] }, { "oidc": [ "jobs:read" ] } ], "description": "Returns a Stripe link where the account holder buys a package, or confirms a move to a larger one. The call charges and changes nothing; the new monthly allowance applies once the account holder completes the Stripe page, usually within a minute. A smaller package is refused with 409 downgrade_requires_dashboard: downgrades are made on the billing page. Send a package, or credits (the smallest package that covers them is chosen), or an empty body to be offered the package that covers 1.5x this month's use. Built for AI agents: hand the url to the person who pays.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string", "enum": [ "seeker", "builder", "growth", "scale", "business" ], "description": "The package to buy. Wins over credits when both are sent." }, "credits": { "type": "integer", "minimum": 1, "description": "Monthly credits wanted; the smallest package that covers them is chosen. Above 500,000 is an Enterprise plan and answers 400." } } }, "example": { "package": "growth" } } } }, "responses": { "200": { "description": "A link to pay or confirm.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "flow", "package", "credits", "price_usd" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Where the account holder pays or confirms. Open it in a browser." }, "flow": { "type": "string", "enum": [ "checkout", "portal" ], "description": "checkout: Stripe Checkout for a new subscription. portal: a Stripe page where the account holder confirms the move to a larger package." }, "package": { "type": "string", "description": "The package chosen." }, "credits": { "type": "integer", "description": "Credits a month on that package." }, "billing_interval": { "type": "string", "enum": [ "month", "year" ], "description": "How the package is billed: the account's current interval (a yearly subscriber stays yearly; credits still arrive every month, and unused credits carry over for 12 months). New purchases here are monthly; yearly is chosen on the billing page." }, "price_usd": { "type": "number", "description": "The package's price in USD per billing_interval." } } }, "example": { "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3", "flow": "checkout", "package": "growth", "credits": 100000, "billing_interval": "month", "price_usd": 149 } } } }, "400": { "description": "Unknown package (bad_package), credits that are not a positive whole number (bad_credits), or more than the largest package (enterprise, with contact_url).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The account already holds that package (already_subscribed), or asked for a smaller one (downgrade_requires_dashboard, with billing_url): downgrades are made on the billing page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutError" } } } }, "502": { "description": "Stripe could not start the checkout (checkout_failed). Retry, or upgrade from the billing page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutError" } } } } }, "tags": [ "Billing" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "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." }, "oidc": { "type": "openIdConnect", "openIdConnectUrl": "https://jobspipe.dev/.well-known/openid-configuration", "description": "OpenID Connect / OAuth 2.0 access via the JobsPipe authorization server. Supported scopes (also advertised in the protected-resource metadata at https://api.jobspipe.dev/.well-known/oauth-protected-resource): jobs:read - search normalized job postings; stack:read - run technology-stack scans." } }, "headers": { "Deprecation": { "description": "Sent only on deprecated endpoints, per the JobsPipe deprecation policy. RFC 9745 date of when the endpoint was or will be deprecated. Absent on current endpoints.", "schema": { "type": "string" } }, "Sunset": { "description": "Sent only on deprecated endpoints, per the JobsPipe deprecation policy. RFC 8594 timestamp after which the endpoint stops working - at least 6 months after the Deprecation date. Absent on current endpoints.", "schema": { "type": "string" } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "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." } }, "schemas": { "InsightCompensationResponse": { "type": "object", "properties": { "occupation_code": { "type": "string", "nullable": true }, "occupation_label": { "type": "string", "nullable": true }, "window_days": { "type": "integer" }, "country": { "type": "string", "nullable": true }, "count": { "type": "integer", "description": "Postings with stated pay in scope." }, "currency": { "type": "string", "enum": [ "USD" ] }, "percentiles": { "type": "object", "nullable": true, "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "suppressed": { "type": "boolean", "description": "True when the sample is under 30 postings." } } }, "InsightBenchmarkRequest": { "type": "object", "description": "Requires occupation_code or title.", "properties": { "occupation_code": { "type": "string", "pattern": "^\\d{1,4}$" }, "title": { "type": "string", "description": "Title substring match, e.g. data engineer." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "seniority": { "type": "string", "enum": [ "entry_level", "mid_level", "senior", "director", "executive", "entry", "mid", "lead", "exec" ], "description": "Preferred: the values a job's seniority field reports, entry_level, mid_level, senior, director and executive. The older names entry, mid, lead and exec still work and mean the same levels: entry is entry_level, mid is mid_level, lead is director, exec is executive. director covers directors and lead, staff and principal roles." }, "window_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } } }, "JobSearchRequest": { "type": "object", "description": "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.", "properties": { "job_title_or": { "type": "array", "items": { "type": "string" }, "maxItems": 60, "description": "Match jobs whose title contains any of these. At most 60." }, "job_title_not": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Exclude jobs whose title contains any of these. At most 100." }, "description_or": { "type": "array", "items": { "type": "string" }, "maxItems": 25, "description": "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. Words match whole: \"engineer\" does not match \"engineering\" or \"engineers\", so list each form you want (for example [\"engineer\", \"engineering\"]). At most 25." }, "description_phrase_or": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 25, "description": "Match jobs whose description contains any one of these exact phrases. The words must appear in this order and next to each other (any spaces or hyphens between them), and each phrase matches whole: \"LangGraph\" does not match \"LangGraphs\". Matching is case-insensitive, except that a phrase written entirely in capitals, such as \"MCP\" or \"E2B\", matches only in capitals, so \"mcp\" in a URL does not count. Use it for product, framework and tool names, where description_or would also match the words scattered apart. Given with description_or, a job must match both. At most 25." }, "description_not": { "type": "array", "items": { "type": "string" }, "maxItems": 25, "description": "Exclude jobs whose description contains every word of any one of these phrases, matched the same way as description_or: whole words, case-insensitive, in any order, not necessarily adjacent. At most 25." }, "job_country_code_or": { "type": "array", "items": { "type": "string" }, "description": "Match any of these ISO alpha-2 country codes, e.g. US, GB." }, "job_country_code_not": { "type": "array", "items": { "type": "string" }, "description": "Exclude these ISO alpha-2 country codes." }, "job_location_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "Match any of these seniority levels." }, "include_unlabeled_employment_type": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "ISIC Rev.4 industry divisions of the employer (2-digit, e.g. 62 = Computer programming and consultancy)." }, "region_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "full-time", "part-time", "contract", "temporary", "internship" ] }, "description": "Match any of these employment types." }, "language_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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, francetravail. ATS (company career sites): greenhouse, workday, ashby, lever, workable, recruitee, personio, smartrecruiters, oracle, icims, successfactors, 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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Match any of these company names (partial / contains). At most 100." }, "company_technology_slug_or": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "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": { "type": "integer", "description": "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": { "type": "integer", "description": "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": { "type": "number", "minimum": 0, "description": "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": { "type": "number", "minimum": 0, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[0-9A-Za-z]{20}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[0-9]{1,20}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "Only jobs at companies headquartered outside these countries (ISO 3166-1 alpha-2). Companies with no known headquarters never match." }, "remote": { "type": "boolean", "description": "true for remote-only, false to exclude remote." }, "work_arrangement_or": { "type": "array", "items": { "type": "string", "enum": [ "remote", "hybrid", "onsite" ] }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "offers", "no", "citizenship_required" ] }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "integer", "minimum": 0, "description": "Only jobs whose applicant_count is at most this value. Only LinkedIn and CV-Library postings carry one, so this filter also drops every job without a count. On LinkedIn the value is a threshold from the posting's badge, not an exact count: 25 means 25 or fewer so far, 200 means more than 200, so 25 keeps the early-applicant postings." }, "has_recruiter_email": { "type": "boolean", "description": "true for only jobs with a recruiter contact email parsed from the posting, false for only jobs without one." }, "min_salary_usd": { "type": "integer", "minimum": 0, "description": "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": { "type": "integer", "minimum": 0, "maximum": 100, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employment_type", "seniority", "work_arrangement", "location", "occupation", "industry", "visa_sponsorship", "benefits", "company_size", "company_revenue", "salary", "language" ] }, "description": "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": { "type": "integer", "minimum": 1, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Only postings newer than this many days, at most 365. Leave it out for the whole corpus." }, "posted_at_gte": { "type": "string", "description": "Only postings on or after this date (YYYY-MM-DD, or an ISO 8601 datetime). Any other value is a 400." }, "posted_at_lte": { "type": "string", "description": "Only postings on or before this date (YYYY-MM-DD, or an ISO 8601 datetime). Any other value is a 400." }, "discovered_at_gte": { "type": "string", "description": "Only postings first discovered by JobsPipe at or after this UTC datetime (YYYY-MM-DD HH:MM:SS, or any ISO 8601 datetime; any other value is a 400). Tracks when we first saw the posting, not when it was posted. A posting can become searchable well after that time, so to poll for new jobs use delta_cursor, which cannot miss one." }, "delta_cursor": { "type": "string", "description": "Opaque cursor from metadata.next_delta_cursor. Returns only postings that became searchable since that cursor was issued, however long before that JobsPipe first discovered them, so a repeating query reads new jobs instead of the whole result set again. A posting that becomes searchable late is still returned, by the next call after it does, with its original discovered_at, so none is missed. The same id can come back when a newer posting replaces the one behind it, so deduplicate by id; a job is billed once per calendar month. Keep the rest of the filters identical between calls, and page with next_cursor. Supersedes discovered_at_gte when both are sent." }, "limit": { "type": "integer", "minimum": 1, "default": 25, "description": "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": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of results to skip. Ignored when cursor is set. A positive offset takes precedence over page." }, "page": { "type": "integer", "minimum": 0, "description": "Zero-based page index: skips page × limit results, at most 10,000 rows deep (a 400 names the field past that). Ignored when cursor is set or offset is positive." }, "cursor": { "type": [ "string", "null" ], "description": "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": { "type": "array", "maxItems": 1, "items": { "type": "object", "required": [ "field" ], "properties": { "field": { "type": "string" }, "desc": { "type": "boolean" } } }, "description": "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": { "type": "string", "enum": [ "active", "closed", "any" ], "default": "active", "description": "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": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "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." }, "company_name_not": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 100, "description": "Exclude jobs at any of these companies. 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 name also excludes the longer names it starts, followed by a space, so Amazon excludes Amazon Web Services but not Amazonia. A name ending in a legal suffix excludes only that company's own spellings: its whole form, as an exact name or a prefix, and the same name with its suffixes dropped, as an exact name, so Capital Group excludes Capital Group Companies and Capital Inc and keeps Capital One. One character or a bare generic word (The, SAS) alone is a 400: add its legal suffix (SAS Inc) to exclude that one company. A name is at most 200 characters and 400 bytes of UTF-8, about 130 characters in Chinese or Japanese. A name made only of punctuation excludes nothing. A job with no company name is never excluded. An excluded job is not returned and costs no credit. At most 100." }, "job_id_or": { "type": "array", "items": { "type": "string" }, "description": "Return jobs whose ID is any of these: the id a search returned, which is the posting's native id on its board, or JobsPipe's internal 16-character id. Behaves the same as job_ids; values from both are combined. The status filter still applies and defaults to active." }, "job_ids": { "type": "array", "items": { "type": "string" }, "description": "Look up these job IDs. Behaves the same as job_id_or: matched against the posting's native id or JobsPipe's internal id, combined with job_id_or, and subject to the status filter, which defaults to active." }, "include_unknown_size": { "type": "boolean", "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employer", "agency", "broker" ] }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employer", "agency", "broker" ] }, "description": "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": { "type": "boolean", "description": "Include the total match count in metadata.total_results." }, "include_technologies": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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." } }, "additionalProperties": false }, "CompanyRecord": { "description": "The company lookup's record: the CompanyObject a job embeds, plus the company's key.", "allOf": [ { "$ref": "#/components/schemas/CompanyObject" }, { "type": "object", "properties": { "key": { "type": [ "string", "null" ], "description": "The company's key: opens GET /v1/jobs/companies/{key} (the company page) and matches company_key_or on job search. Null when the record has no postings behind it." } }, "required": [ "key" ] } ] }, "CompanyObject": { "type": "object", "description": "Structured details about the hiring company. Every field is independently optional.", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ], "description": "Bare website host, e.g. stripe.com." }, "url": { "type": [ "string", "null" ], "description": "Company website." }, "logo": { "type": [ "string", "null" ] }, "employee_count": { "type": [ "integer", "null" ], "description": "Headcount from the company's public profile or, failing that, from the employer's business record, which may be an estimate." }, "employee_count_min": { "type": [ "integer", "null" ], "description": "Lower bound on headcount, when only a size band is known (e.g. 10000 for a \"10,000+\" company). Present for many companies that have no exact count." }, "linkedin_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "object", "null" ], "description": "Company headquarters.", "properties": { "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "founded": { "type": [ "string", "null" ], "description": "Year the company was founded, where known." }, "intelligence": { "type": [ "object", "null" ], "description": "Revenue, legal identity and entity type of the employer, resolved for the posting's company in the posting's country. Null when no record exists or the record holds no finding, and always null on GET /v1/companies/{key}, which has no posting country to resolve against. Every field inside is independently null when it is not known.", "properties": { "revenue_usd": { "type": [ "number", "null" ], "description": "Most recent known annual revenue, converted to US dollars. Null when no figure is known." }, "revenue_year": { "type": [ "integer", "null" ], "description": "Fiscal year the revenue figure refers to." }, "revenue_source": { "type": [ "string", "null" ], "enum": [ "filing", "directory", null ], "description": "Where the revenue figure came from: filing = the company's statutory accounts or a securities filing; directory = any other source, such as a company directory." }, "revenue_confidence": { "type": [ "string", "null" ], "enum": [ "filed", "reported", "band", "derived", "extracted", null ], "description": "How the revenue figure was obtained, strongest first: filed = taken from the company's statutory accounts; reported = stated by the company itself; band = only an estimated range is known; revenue_usd is a representative figure within it; derived = estimated from funding or valuation; extracted = read from public text about the company." }, "entity_kind": { "type": [ "string", "null" ], "description": "What kind of organisation the employer is: company, branch, public_sector or staffing_agency." }, "founded_year": { "type": [ "integer", "null" ], "description": "Year the legal entity was founded or registered." }, "headcount": { "type": [ "integer", "null" ], "description": "Employee count as filed, registered or listed in a company directory. Can differ from employee_count, which comes from the company's public profile." }, "industry": { "type": [ "string", "null" ], "description": "Industry as recorded for the legal entity or, where no record exists, the industry a company directory lists." }, "hq_region": { "type": [ "string", "null" ], "description": "Region or state of the employer's headquarters, as written by the source (for example California), when known." }, "hq_city": { "type": [ "string", "null" ], "description": "City of the employer's headquarters, when known." }, "revenue_low_usd": { "type": [ "number", "null" ], "description": "Lower bound of the revenue, in US dollars: the range behind the figure when the source gave one; null otherwise." }, "revenue_high_usd": { "type": [ "number", "null" ], "description": "Upper bound of the revenue, in US dollars: the range behind the figure when the source gave one; null otherwise." }, "headcount_low": { "type": [ "integer", "null" ], "description": "Lower bound of the headcount: the range behind the figure when the source gave one; null otherwise." }, "headcount_high": { "type": [ "integer", "null" ], "description": "Upper bound of the headcount: the range behind the figure when the source gave one; null otherwise." }, "lei": { "type": [ "string", "null" ], "description": "The company's Legal Entity Identifier (ISO 17442), 20 characters. Null when we have not identified the company's legal entity." }, "legal_name": { "type": [ "string", "null" ], "description": "The registered legal name of the entity `lei` identifies. Null when `lei` is null." }, "group_lei": { "type": [ "string", "null" ], "description": "The LEI of the corporate group the company belongs to: its ultimate parent, or its direct parent when no ultimate parent is recorded. Null when the company has no recorded parent, or when `lei` is null. Can equal `lei` when the company heads its own group." }, "group_name": { "type": [ "string", "null" ], "description": "The registered legal name of the entity `group_lei` identifies. Null when `group_lei` is null." } } } } }, "JobTechnology": { "type": "object", "description": "One technology a posting names, graded. Beta: served while the per-job technologies flag is on.", "required": [ "slug", "name", "kind", "category", "parent_category", "logo", "strength", "confidence", "sections", "in_title", "terms", "terms_cs" ], "properties": { "slug": { "type": "string", "description": "Taxonomy slug, e.g. \"snowflake\" or \".net\"." }, "name": { "type": "string", "description": "Display name, e.g. \"Snowflake\"." }, "kind": { "type": "string", "description": "product, language, framework, methodology, certification or standard." }, "category": { "type": "string", "description": "e.g. \"Databases\". Empty string when unknown." }, "parent_category": { "type": "string", "description": "e.g. \"Software and tools\". Empty string when unknown." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Absolute URL of the technology's logo; null when there is none." }, "strength": { "type": "string", "enum": [ "required", "preferred", "mentioned" ], "description": "required = the posting asks for it; preferred = a nice-to-have; mentioned = named without being asked for. The strongest reading of the posting." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "high = independent checks agree the posting names it; medium = required or in the title; low = otherwise." }, "sections": { "type": "array", "items": { "type": "string" }, "description": "Posting sections it appears in, e.g. [\"requirements\"]." }, "in_title": { "type": "boolean", "description": "Whether the job title names it." }, "terms": { "type": "array", "items": { "type": "string" }, "description": "Case-insensitive text forms that find the mention in description." }, "terms_cs": { "type": "array", "items": { "type": "string" }, "description": "Case-sensitive text forms, e.g. \"Go\" or \"R\"." } } }, "JobSource": { "type": "object", "description": "One board a posting was seen on.", "properties": { "provider": { "type": "string", "description": "Collector source the posting was seen on, e.g. linkedin, indeed." }, "url": { "type": [ "string", "null" ], "description": "The posting's URL on that source." }, "seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the posting was seen on that source." } } }, "Job": { "type": "object", "description": "A normalized job posting.", "properties": { "id": { "type": [ "string", "number" ], "description": "The posting's ID on the source JobsPipe attributes it to, so its format varies (a number, a UUID, a hex string): treat it as an opaque string. Stable for the same posting over time, so store it and look the posting up by it. Postings are matched across sources by employer, title and country: a role listed on several boards under one employer is returned once per city, under this one ID. A lookup by job_ids with another board's own ID returns that board's copy, with its own id and source_url. When boards name the employer differently, each copy is its own record with its own ID." }, "job_title": { "type": "string" }, "normalized_title": { "type": [ "string", "null" ], "description": "Canonical form of the title, assigned by the same title classifier that fills occupation_code. Null until the title has been classified." }, "company": { "type": "string" }, "company_domain": { "type": [ "string", "null" ], "description": "Hiring company's website domain, for CRM and account matching. Resolved from the company name where a source did not supply one." }, "company_object": { "anyOf": [ { "$ref": "#/components/schemas/CompanyObject" }, { "type": "null" } ], "description": "Structured company details, or null when nothing beyond the name is known. Fields are independently optional: coverage depends on which source resolved the company." }, "employer_type": { "type": "string", "description": "Who posted the job: \"employer\" (hires for itself), \"agency\" (staffing or recruitment firm posting for a client) or \"broker\" (job board republishing another company's listing). Defaults to \"employer\" where the company has not been classified." }, "location": { "type": [ "string", "null" ] }, "short_location": { "type": [ "string", "null" ], "description": "Identical to location: JobsPipe publishes the board's own location string in location, short_location and long_location. The parsed parts are in cities, state_code, country_code and postal_code." }, "long_location": { "type": [ "string", "null" ], "description": "The same raw location string as location, under the same rules as short_location." }, "country_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "Country name for country_code, e.g. United States. Derived from the code, which sources publish far more often than the name." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "country as a single-element array, empty when the country is unknown. Only the posting's primary location is published, so it never holds more than one element." }, "country_codes": { "type": "array", "items": { "type": "string" }, "description": "country_code as a single-element array, empty when the country is unknown. Only the posting's primary location is published, so it never holds more than one element." }, "continents": { "type": "array", "items": { "type": "string" }, "description": "Continent for country_code as a single-element array, e.g. [\"Europe\"]. Empty when the country is unknown." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude of the job's location: the posting's own coordinates when the job board published them. City-centre coordinates are being switched on, and as they are, a posting whose city is known is filled from the centre of that city instead. Read coordinates_source to tell the two apart. Null when there are none." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude of the job's location, under the same rules as latitude." }, "coordinates_source": { "type": [ "string", "null" ], "enum": [ "source", "city_centroid", null ], "description": "Where latitude and longitude come from. \"source\": the job board published them for this posting. \"city_centroid\": the centre of the posting's city, not the employer's address, so do not treat it as a precise location. Null when there are no coordinates." }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code of the job's location, when the source published one. Distinct from company_object.location.postal_code, which is the employer's headquarters." }, "state_code": { "type": [ "string", "null" ], "description": "Region or state of the job's location, as the source published it (e.g. WA, or a spelled-out region). Not guaranteed to be a two-letter code." }, "cities": { "type": "array", "items": { "type": "string" }, "description": "The job's city as a single-element array, empty when the source published no city." }, "remote": { "type": [ "boolean", "null" ] }, "hybrid": { "type": [ "boolean", "null" ], "description": "True when work_arrangement is hybrid, false when it is remote or onsite, null when the arrangement is unknown. Never false on a guess." }, "seniority": { "type": [ "string", "null" ] }, "employment_statuses": { "type": "array", "items": { "type": "string" }, "description": "The job's employment type as a single-element array: full_time, part_time, contract, temporary or internship. Empty when the posting does not state one. Note the underscored spelling; the employment_type_or filter takes the hyphenated form." }, "date_posted": { "type": [ "string", "null" ], "description": "When the job was posted, normalised: a source date before 2015 or in the future, or no source date at all, is replaced by the date JobsPipe first saw the posting, so it is always the value the posted_at_* filters and the sort use. The source's unmodified date is not exposed." }, "discovered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When JobsPipe first saw the posting, which can be well before it became searchable. Poll with delta_cursor to fetch only what is new since your last run." }, "status": { "type": "string", "description": "Lifecycle state: active or closed. Postings no status recheck has reached yet report active." }, "closed_at": { "type": [ "string", "null" ], "description": "When the posting was closed, as YYYY-MM-DD HH:MM:SS in UTC (a space separator, not the RFC 3339 T). Null while the job is active." }, "closed_reason": { "type": [ "string", "null" ], "description": "Why the posting closed: closed (the source said so), gone (the posting disappeared) or stale (unseen long enough to be treated as closed). Null while the job is active." }, "has_blurred_data": { "type": "boolean", "description": "DEPRECATED. Always false: preview mode has been removed and every record is returned unmasked." }, "url": { "type": [ "string", "null" ], "description": "Link to the posting." }, "source_url": { "type": [ "string", "null" ], "description": "The posting's URL on the first entry of sources, falling back to url. See sources for every board it was seen on." }, "final_url": { "type": [ "string", "null" ], "description": "The employer's own apply page (usually its ATS) when the board the posting came from links off-site; null otherwise. url stays the board's posting." }, "salary_string": { "type": [ "string", "null" ], "description": "The pay as written in the posting, e.g. \"$120K - $150K a year\" or \"$45 an hour\". Present only when the posting states pay; null otherwise. Roughly a quarter of postings disclose pay." }, "salary_currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code of the salary, e.g. USD, GBP, EUR." }, "min_annual_salary": { "type": [ "integer", "null" ], "description": "Minimum pay annualized to a yearly figure in the original currency. Hourly, daily, weekly and monthly rates are scaled to a year; salary_string preserves the original." }, "max_annual_salary": { "type": [ "integer", "null" ], "description": "Maximum pay annualized to a yearly figure in the original currency." }, "min_annual_salary_usd": { "type": [ "integer", "null" ], "description": "min_annual_salary converted to USD. Non-USD pay is converted through a pinned ECB exchange-rate snapshot rather than a live rate, so the same posting always converts to the same figure. Null when the posting discloses no pay or no rate exists for its currency." }, "max_annual_salary_usd": { "type": [ "integer", "null" ], "description": "max_annual_salary converted to USD, under the same rules as min_annual_salary_usd." }, "avg_annual_salary_usd": { "type": [ "integer", "null" ], "description": "Midpoint of min_annual_salary_usd and max_annual_salary_usd, rounded. When only one of the two is known, that value; null when neither is." }, "keyword_slugs": { "type": "array", "items": { "type": "string" }, "description": "Skill slugs extracted from the title and description against a curated lexicon, e.g. python, kubernetes, financial-modeling." }, "technology_slugs": { "type": "array", "items": { "type": "string" }, "description": "The older, ungraded technology list, kept for compatibility; prefer technologies. Named technologies: languages, frameworks, products, tools and platforms, plus named standards and certifications (e.g. python, snowflake, soc2). Broader skills and concepts such as ci/cd or machine-learning appear only in keyword_slugs." }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/JobTechnology" }, "description": "Beta. Technologies the posting names, graded by strength and confidence. Present only when the request set include_technologies, and then on every job; empty until the posting has been extracted or while the feature is off. Costs 1 extra credit per job that names at least one, once per job per calendar month. Sorted required, preferred, mentioned; then confidence high to low; then name." }, "occupation_code": { "type": [ "string", "null" ], "description": "ISCO-08 unit group of the role (4-digit), e.g. 2512 = Software Developers." }, "occupation_label": { "type": [ "string", "null" ], "description": "Human-readable ISCO-08 unit group label." }, "isic_division": { "type": [ "string", "null" ], "description": "ISIC Rev.4 industry division of the employer (2-digit), e.g. 62 = Computer programming and consultancy." }, "isic_division_label": { "type": [ "string", "null" ], "description": "Human-readable ISIC Rev.4 division label." }, "description": { "type": [ "string", "null" ], "description": "Full text of the posting as published by the source." }, "easy_apply": { "type": [ "boolean", "null" ], "description": "Always null: JobsPipe does not detect one-click apply." }, "hiring_team": { "type": "array", "items": {}, "description": "Always empty: JobsPipe does not publish named recruiter contacts." }, "reposted": { "type": "boolean", "description": "True when LinkedIn re-listed this posting after JobsPipe first saw it: the same LinkedIn job, with a listed date at least two calendar days (UTC) later than discovered_at, collected within a day of that date. False otherwise, which includes every other source, a posting LinkedIn gave no date for, and a re-listing JobsPipe did not collect, so false does not prove a posting was never reposted." }, "date_reposted": { "type": [ "string", "null" ], "description": "The newest listed date when reposted is true, the same value as date_posted; discovered_at keeps when JobsPipe first saw the posting. Null when reposted is false." }, "matching_phrases": { "type": "array", "items": { "type": "string" }, "description": "Always empty." }, "matching_words": { "type": "array", "items": { "type": "string" }, "description": "Always empty, under the same rules as matching_phrases." }, "work_arrangement": { "type": [ "string", "null" ], "description": "How the role is worked: remote, hybrid or onsite. Null when the posting does not say. Finer than remote, which answers false for hybrid and onsite alike; filter on it with work_arrangement_or." }, "is_manager": { "type": [ "boolean", "null" ], "description": "Whether the role manages people. seniority maps our lead bucket to \"director\", which files staff and principal individual contributors under a title that reads as people management; this field tells them apart. Null until the title has been classified." }, "job_function": { "type": [ "string", "null" ], "description": "Coarse function of the role, from a closed vocabulary: Engineering, Data & Analytics, Product, Design, IT & Security, Sales, Marketing, Customer Support, Operations, Finance & Accounting, Legal, Human Resources, Healthcare, Education, Science & Research, Manufacturing, Logistics & Supply Chain, Construction & Trades, Hospitality & Food, Retail, Transport, Security & Protective, Administration, Executive. Null until the title has been classified." }, "last_seen_at": { "type": [ "string", "null" ], "description": "When JobsPipe last saw the posting live, on a collection run or a recheck, as YYYY-MM-DD HH:MM:SS in UTC (a space separator, not the RFC 3339 T). Usually null once the posting is closed." }, "verified_at": { "type": [ "string", "null" ], "description": "When JobsPipe last updated the posting's status (a collection run, a recheck or a close), as YYYY-MM-DD HH:MM:SS in UTC (a space separator, not the RFC 3339 T). To tell whether a posting is open, read status." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/JobSource" }, "description": "Every source this posting was seen on. Normally one entry: the board the posting is attributed to, whose ID is id. Other boards' copies of the same role are their own postings, so this does not list every board a role appears on. Empty when no source entry was stored." }, "work_arrangement_source": { "type": [ "string", "null" ], "description": "How work_arrangement was decided: \"source\" (declared by the job board) or \"text\" (parsed from the description)." }, "visa_sponsorship": { "type": [ "string", "null" ], "description": "Visa stance parsed from the posting: \"offers\", \"no\" or \"citizenship_required\". Null where the posting says nothing." }, "benefits": { "type": "array", "items": { "type": "string" }, "description": "Benefit slugs from structured source data. Empty where the source exposes none." }, "salary_source": { "type": [ "string", "null" ], "description": "Where the salary came from: \"source\" (structured data from the board) or \"description\" (parsed from the posting text)." }, "salary_type": { "type": [ "string", "null" ], "description": "\"observed\" when the posting itself carries pay, \"estimated\" when only the corpus benchmark does, null when neither." }, "estimated_min_annual_salary_usd": { "type": [ "number", "null" ], "description": "25th-percentile annual USD pay for this occupation and location, from public salary statistics. A benchmark, not the employer's posted pay; published beside any observed salary." }, "estimated_avg_annual_salary_usd": { "type": [ "number", "null" ], "description": "Median benchmark. See estimated_min_annual_salary_usd." }, "estimated_max_annual_salary_usd": { "type": [ "number", "null" ], "description": "75th-percentile benchmark. See estimated_min_annual_salary_usd." }, "expires_at": { "type": [ "string", "null" ], "description": "Application deadline where the source publishes one. Format: YYYY-MM-DD HH:MM:SS (UTC)." }, "applicant_count": { "type": [ "integer", "null" ], "description": "How many people have applied, as the source shows it (LinkedIn and CV-Library only). On LinkedIn it is a threshold from the posting's badge, not an exact count: 25 means 25 or fewer so far, 200 means more than 200, and a value in between is the number LinkedIn showed." }, "recruiter_emails": { "type": "array", "items": { "type": "string" }, "description": "Recruiter contact emails parsed from the posting text." }, "listing_type": { "type": [ "string", "null" ], "description": "How the posting was listed where the source exposes it." }, "metro_code": { "type": [ "string", "null" ], "description": "US CBSA metro code resolved from the job's location. Null outside covered metros." }, "metro_label": { "type": [ "string", "null" ], "description": "Metro display name for metro_code, e.g. \"New York-Newark-Jersey City, NY-NJ\"." }, "normalized_city": { "type": [ "string", "null" ], "description": "The city the posting names, in one canonical spelling (\"Munich\" for a posting stored as \"München\", \"London\" for \"London Area\" or \"Mayfair\"). null when the location could not be placed. city_or matches on it." }, "seniority_source": { "type": [ "string", "null" ], "description": "How seniority was decided: \"source\", \"title\" or \"onet_prior\" (occupation-level prior)." }, "esco_skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": [ "string", "null" ] } } }, "description": "ESCO skill concepts for this job's extracted skills, as stable id/label pairs." }, "ghost_score": { "type": [ "number", "null" ], "description": "0-100 likelihood the posting is stale or evergreen rather than a live vacancy, from repost cadence, tenure and content signals. Null until scored." }, "language": { "type": [ "string", "null" ], "description": "The language the posting text is written in, as a lowercase ISO 639-1 code, e.g. \"en\", \"sv\", \"de\". The language of the posting, not of the country it sits in. Null until the posting has been labelled." } } }, "JobSearchResponse": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "type": "object", "description": "Counts, the pagination cursor, and what the call cost.", "properties": { "total_results": { "type": [ "integer", "null" ] }, "truncated_results": { "type": "integer" }, "total_companies": { "type": [ "integer", "null" ], "description": "Always null on job search. For a distinct-company count use POST /v1/jobs/companies." }, "truncated_companies": { "type": "integer", "description": "Always 0, under the same rules as total_companies." }, "next_cursor": { "type": [ "string", "null" ] }, "next_delta_cursor": { "type": [ "string", "null" ], "description": "Pass as delta_cursor on the next run of this same query to get only postings that have become searchable since this result. Null while next_cursor is set: the position is only meaningful once you have read the whole result set, so finish paging first and use the cursor from the last page." }, "delta_delayed": { "type": "boolean", "description": "Present and true when this delta_cursor poll could not be answered for now. data is empty, nothing is charged, and next_delta_cursor is the cursor you sent, so nothing is lost: run the same poll again later." }, "credits_charged": { "type": "integer", "description": "Credits this call cost: the jobs in data that the account had not already paid for this calendar month (UTC), plus technologies_credits_charged when include_technologies was set. Absent for callers that are not metered." }, "jobs_already_paid": { "type": "integer", "description": "Jobs in data that cost nothing because the account already paid for them this calendar month. Without include_technologies, credits_charged plus jobs_already_paid equals the number of jobs returned." }, "technologies_credits_charged": { "type": "integer", "description": "Present only with include_technologies. The part of credits_charged spent on technologies: 1 per returned job that names at least one technology and whose technologies the account had not already paid for this calendar month." }, "technologies_already_paid": { "type": "integer", "description": "Present only with include_technologies. Jobs whose technologies cost nothing because the account already paid for them this calendar month." }, "credits_remaining": { "type": "integer", "description": "Credits the account can still spend after this call: what is left of the monthly allowance plus extra credits, or on Free what is left of the one-time grant. Absent for callers that are not metered." }, "credits_allowance": { "type": "integer", "description": "What credits_remaining is measured against: the monthly allowance on a paid package, the one-time grant on Free. Absent for callers that are not metered." }, "field_coverage": { "type": "object", "description": "For each filter the request used that reads a partially filled field: the share (0-100) of active postings from the last 30 days carrying it, overall and per source.", "additionalProperties": { "type": "object", "properties": { "field": { "type": "string" }, "filled_pct": { "type": "number" }, "by_source": { "type": "object", "additionalProperties": { "type": "number" } } } } } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" }, "description": "The page of matching job postings." } } }, "AgenticSearchRequest": { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500, "description": "What the caller is looking for, in plain language, e.g. \"senior backend engineer in Berlin, visa sponsorship, hybrid ok\"." }, "filters": { "type": "object", "additionalProperties": true, "description": "Hard filters applied to every planned search, in the filter names of /v1/jobs/search (job_country_code_or, city_or, region_or, remote, posted_at_max_age_days, posted_at_gte, posted_at_lte, language_or, ...). Unknown keys are ignored. Paging and ordering keys are not accepted. posted_at_gte, posted_at_lte and discovered_at_gte take a date (YYYY-MM-DD) or an ISO 8601 datetime; any other value is a 400 naming the field." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10, "description": "Postings to return, at most 25 and never more than the plan's page size." } } }, "AgenticSearchResponse": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "type": "object", "description": "What the call cost and how the page was produced. total_results and next_cursor are always null: the page is the answer, not a window on a larger set.", "properties": { "total_results": { "type": [ "integer", "null" ] }, "truncated_results": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "credits_charged": { "type": "integer", "description": "Credits this call cost, the same number the account's usage log shows. Jobs the account already paid for this calendar month (UTC) are free." }, "jobs_already_paid": { "type": "integer" }, "credits_remaining": { "type": "integer", "description": "Credits the account can still spend after this call: what is left of the monthly allowance plus extra credits, or on Free what is left of the one-time grant. Absent for callers that are not metered." }, "credits_allowance": { "type": "integer", "description": "What credits_remaining is measured against: the monthly allowance on a paid package, the one-time grant on Free. Absent for callers that are not metered." }, "agentic": { "type": "object", "description": "The plan and its execution, for transparency and debugging.", "properties": { "intent": { "type": "string", "description": "The request restated in one sentence." }, "role_intent": { "type": "string", "description": "The role, level and field alone; what the relevance score judges." }, "rounds": { "type": "integer", "description": "Planning rounds run, 1 to 3." }, "stop": { "type": "string", "description": "Why the loop stopped, e.g. \"enough candidates passed\"." }, "candidates": { "type": "integer", "description": "Distinct postings considered." }, "dropped": { "type": "integer", "description": "Candidates removed by the hard-constraint checks." }, "passed": { "type": "integer", "description": "Candidates whose relevance cleared the bar." }, "fallback_used": { "type": "boolean", "description": "True when the planner was unavailable and the request words were searched as a title instead." }, "excluded_employers": { "type": "array", "items": { "type": "string" }, "description": "The employers left out of every search: those in filters.company_name_not and those the planner read from the request. With fallback_used the request's words were not read, so only the first kind applies." }, "lanes": { "type": "array", "description": "Each structured search that ran, with its filters and what it returned.", "items": { "type": "object", "properties": { "round": { "type": "integer" }, "name": { "type": "string" }, "filters": { "type": "object", "additionalProperties": true }, "returned": { "type": "integer" }, "relevant": { "type": "integer" }, "ms": { "type": "integer" }, "error": { "type": "string" } } } }, "judge": { "type": "array", "description": "Conditions read from each posting's text, e.g. whether the employer sponsors visas.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "question": { "type": "string" }, "want": { "type": "string", "enum": [ "yes", "no" ], "description": "The answer the request wants: no for an exclusion such as \"not hospitals\"." }, "hard": { "type": "boolean" } } } }, "verify": { "type": "object", "additionalProperties": true, "description": "Hard rules checked on the stored record." }, "jev_calls": { "type": "integer" }, "jev_failed_batches": { "type": "integer" }, "recheck": { "type": "object", "description": "The second look at the shortlist: a stricter judgment of exact role and level against the request's own words.", "properties": { "ran": { "type": "boolean" }, "candidates": { "type": "integer" }, "failed": { "type": "boolean" }, "ms": { "type": "number" } } }, "timings": { "type": "object", "properties": { "planner_ms": { "type": "number" }, "search_ms": { "type": "number" }, "jev_ms": { "type": "number" }, "total_ms": { "type": "number" } } } } } } }, "data": { "type": "array", "description": "The best-matching postings, highest relevance first. Postings scored below 0.3 are never returned, so data can be shorter than limit, or empty.", "items": { "allOf": [ { "$ref": "#/components/schemas/Job" }, { "type": "object", "properties": { "relevance": { "type": [ "number", "null" ], "description": "0-1: how well the posting matches the role asked for, scaled by any text conditions in the request. null when scoring was unavailable and the page is newest-first." }, "judgments": { "type": [ "object", "null" ], "description": "The raw judgments behind relevance: role relevance and, per condition, the probabilities that the text states yes, states no, or says nothing.", "properties": { "relevance": { "type": "number" }, "injection": { "type": "number", "description": "Probability that the posting text tries to instruct the system reading it. At 0.7 or above the posting is never returned." }, "recheck": { "type": "number", "description": "The shortlist re-check: probability that the requester would apply, judged on exact role and level." }, "constraints": { "type": "object", "additionalProperties": { "type": "object", "properties": { "yes": { "type": "number" }, "no": { "type": "number" }, "not_stated": { "type": "number" } } } } } }, "uncertain": { "type": "boolean", "description": "judgments.relevance is between 0.3 and 0.7, where the role judgment is least stable; worth a human look." }, "lanes": { "type": "array", "items": { "type": "string" }, "description": "Which planned searches returned this posting." } } } ] } } } }, "EnrichEmailRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "The people to look up. Each needs linkedin_url, or full_name and domain.", "items": { "type": "object", "properties": { "linkedin_url": { "type": "string", "description": "The person's LinkedIn profile URL." }, "full_name": { "type": "string", "description": "The person's full name, with domain." }, "domain": { "type": "string", "description": "The company's website domain, e.g. acme.com, with full_name." }, "type": { "type": "string", "enum": [ "work", "personal" ], "description": "work (default) or personal. A personal email needs linkedin_url." } } } } } }, "EnrichPhoneRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "The people to look up. Each needs linkedin_url, or full_name and domain; only linkedin_url items can be found.", "items": { "type": "object", "properties": { "linkedin_url": { "type": "string", "description": "The person's LinkedIn profile URL." }, "full_name": { "type": "string", "description": "The person's full name, with domain." }, "domain": { "type": "string", "description": "The company's website domain, e.g. acme.com, with full_name." } } } } } }, "EnrichResponse": { "type": "object", "required": [ "results", "found", "credits_charged" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "index", "status", "type", "value", "credits" ], "properties": { "index": { "type": "integer", "description": "The item's position in the request, from 0." }, "status": { "type": "string", "enum": [ "enriched", "cached", "not_found", "insufficient_credits", "rate_limited", "error" ], "description": "enriched: found and charged now. cached: this account revealed it before, free. Every other status is free; insufficient_credits items were not looked up." }, "type": { "type": "string", "enum": [ "work", "personal", "phone" ] }, "value": { "type": "string", "nullable": true, "description": "The email or phone, or null when none was found." }, "credits": { "type": "integer", "description": "Credits charged for this item." } } } }, "found": { "type": "integer", "description": "Items with a value (enriched or cached)." }, "credits_charged": { "type": "integer", "description": "Credits charged for the whole batch." } } }, "StackScanRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "The domain to scan, e.g. stripe.com." }, "mode": { "type": "string", "enum": [ "auto", "html", "render" ], "description": "Optional scan mode. Defaults to auto." } } }, "DetectedTech": { "type": "object", "description": "A technology detected on the scanned domain.", "required": [ "slug", "name", "categories", "confidence", "signals", "pricing", "saas", "oss" ], "properties": { "slug": { "type": "string", "description": "Stable technology identifier, e.g. 'nextjs'." }, "name": { "type": "string", "description": "Display name, e.g. 'Next.js'." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categories the technology belongs to, e.g. 'Web frameworks', 'Analytics'." }, "confidence": { "type": "number", "description": "0-100 match confidence for this detection." }, "version": { "type": "string", "nullable": true, "description": "Detected version, when the fingerprint reveals one." }, "signals": { "type": "array", "description": "The evidence behind the detection: what kind of fingerprint matched and the matched value.", "items": { "type": "object", "required": [ "kind", "match" ], "properties": { "kind": { "type": "string", "description": "Signal type, e.g. 'header', 'script', 'meta', 'cookie'." }, "match": { "type": "string", "description": "The matched fingerprint value." } } } }, "description": { "type": "string", "nullable": true, "description": "Short description of the technology." }, "website": { "type": "string", "nullable": true, "description": "The technology vendor's website." }, "icon": { "type": "string", "nullable": true, "description": "Icon identifier for the technology." }, "pricing": { "type": "array", "items": { "type": "string" }, "description": "Pricing traits, e.g. 'freemium', 'payg'." }, "saas": { "type": "boolean", "description": "True if offered as a hosted SaaS." }, "oss": { "type": "boolean", "description": "True if open source." } } }, "StackScanResponse": { "type": "object", "required": [ "domain", "scanned_at", "http_status", "detected" ], "properties": { "domain": { "type": "string", "description": "The normalized domain that was scanned." }, "scanned_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the scan was performed." }, "http_status": { "type": "integer", "description": "HTTP status code returned by the scanned domain." }, "detected": { "type": "array", "items": { "$ref": "#/components/schemas/DetectedTech" }, "description": "The technologies detected on the domain." } } }, "Technology": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "category_slug": { "type": "string", "nullable": true }, "parent_category": { "type": "string", "nullable": true }, "kind": { "type": "string", "nullable": true, "description": "product, methodology, certification or standard." }, "logo": { "type": "string", "nullable": true } } }, "TechnologyFound": { "type": "object", "properties": { "technology": { "$ref": "#/components/schemas/Technology" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "high = confirmed, medium = likely, low = mentioned." }, "tier": { "type": "string", "enum": [ "confirmed", "likely", "mentioned" ] }, "jobs": { "type": "integer", "description": "Postings that name the technology." }, "jobs_last_7_days": { "type": "integer" }, "jobs_last_30_days": { "type": "integer" }, "jobs_last_180_days": { "type": "integer" }, "first_date_found": { "type": "string", "format": "date", "nullable": true }, "last_date_found": { "type": "string", "format": "date", "nullable": true }, "rank_within_category": { "type": "integer", "nullable": true }, "relative_occurrence_within_category": { "type": "number", "nullable": true }, "required_jobs": { "type": "integer" }, "preferred_jobs": { "type": "integer" }, "mentioned_jobs": { "type": "integer" }, "recency": { "type": "string", "enum": [ "active", "fading", "historical" ] }, "share": { "type": "number", "nullable": true, "description": "Share of the company's postings that name the technology." }, "occupations": { "type": "array", "items": { "type": "string" }, "description": "ISCO-08 codes of the roles that name it." }, "countries": { "type": "array", "items": { "type": "string" } }, "sample_jobs": { "type": "array", "items": { "$ref": "#/components/schemas/SampleJob" }, "description": "Only with include_sample_jobs: up to 3 of the newest postings from the last 180 days that named the technology." } }, "description": "With detail: compact only technology (slug and name), confidence, tier, jobs, jobs_last_30_days, required_jobs, first_date_found and last_date_found are present." }, "SampleJob": { "type": "object", "properties": { "id": { "type": "string", "description": "The posting's JobsPipe id, usable with job_id_or and the job endpoints." }, "title": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true, "description": "The original posting." }, "posted_at": { "type": "string", "nullable": true } } }, "TechCompany": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "employee_count": { "type": "integer", "nullable": true }, "employee_count_range": { "type": "string", "nullable": true }, "founded_year": { "type": "integer", "nullable": true }, "annual_revenue_usd": { "type": "number", "nullable": true }, "industry": { "type": "string", "nullable": true }, "linkedin_url": { "type": "string", "nullable": true }, "num_jobs": { "type": "integer" }, "num_jobs_found": { "type": "integer" }, "num_jobs_last_30_days": { "type": "integer" }, "num_technologies": { "type": "integer", "description": "Absent with detail: compact." }, "technology_slugs": { "type": "array", "items": { "type": "string" }, "description": "Absent with detail: compact." }, "technology_names": { "type": "array", "items": { "type": "string" }, "description": "Absent with detail: compact." }, "technologies_found": { "type": "array", "items": { "$ref": "#/components/schemas/TechnologyFound" } } } }, "CompanySearchRequest": { "type": "object", "additionalProperties": false, "properties": { "company_technology_slug_or": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "company_technology_slug_and": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "company_technology_slug_not": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "expand_technology_slugs": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "min_num_jobs_found": { "type": "integer", "minimum": 1 }, "company_country_code_or": { "type": "array", "items": { "type": "string" }, "description": "Countries of the postings that name the technology." }, "company_domain_or": { "type": "array", "items": { "type": "string" } }, "company_name_or": { "type": "array", "items": { "type": "string" } }, "min_employee_count": { "type": "integer", "minimum": 0 }, "max_employee_count": { "type": "integer", "minimum": 0 }, "include_total_results": { "type": "boolean" }, "order_by": { "type": "array", "maxItems": 3, "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "num_jobs", "num_jobs_found", "num_jobs_last_30_days", "employee_count" ] }, "desc": { "type": "boolean", "default": true } }, "required": [ "field" ] } }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25 }, "page": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "cursor": { "type": "string" }, "tier_min": { "type": "string", "enum": [ "confirmed", "likely", "mentioned" ], "default": "likely" }, "detail": { "type": "string", "enum": [ "compact", "full" ], "default": "full", "description": "compact answers each company without technology_slugs, technology_names and num_technologies and trims each technologies_found entry to the technology, tier, confidence, jobs, jobs_last_30_days, required_jobs and the first and last date found: about 500 bytes per company. full is the whole stack." }, "include_sample_jobs": { "type": "boolean", "default": false, "description": "Add sample_jobs to each technologies_found entry: up to 3 of the newest postings from the last 180 days that named the technology, with id, title, url and posted_at. No extra credits." }, "job_filters": { "type": "object", "description": "Only job_country_code_or and posted_at_max_age_days are applied; other job filters are accepted and ignored.", "properties": { "job_country_code_or": { "type": "array", "items": { "type": "string" } }, "posted_at_max_age_days": { "type": "integer", "minimum": 1 } } } } }, "CompanySearchResponse": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "total_results": { "type": "integer" }, "total_companies": { "type": "integer" }, "truncated_results": { "type": "integer" }, "truncated_companies": { "type": "integer" }, "credits_charged": { "type": "integer" }, "companies_already_paid": { "type": "integer" }, "credits_remaining": { "type": "integer", "description": "Credits the account can still spend after this call. Absent for callers that are not metered." }, "credits_allowance": { "type": "integer", "description": "What credits_remaining is measured against: the monthly allowance, or Free's one-time grant." }, "next_cursor": { "type": "string", "nullable": true }, "as_of": { "type": "string", "nullable": true } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TechCompany" } } } }, "CompanyTechnologiesResponse": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "linkedin_url": { "type": "string", "nullable": true } } }, "num_jobs": { "type": "integer" }, "num_technologies": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TechnologyFound" } } } }, "TechResolveRequest": { "type": "object", "additionalProperties": false, "required": [ "names" ], "properties": { "names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 2000, "description": "Technology or product names as you have them, or vendor domains such as okta.com." } } }, "TechResolveResponse": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name as sent." }, "slug": { "type": "string", "nullable": true, "description": "The technology slug to search with, or null when the name is not tracked." }, "technology_name": { "type": "string", "nullable": true }, "match": { "type": "string", "enum": [ "exact", "alias", "domain", "prefix", "none" ], "description": "exact: the name itself. alias: a known alias once marketplace words are dropped. domain: a vendor's domain. prefix: the name starts with the technology, so check it. none: not tracked (no signal, not proof it is unused)." }, "companies": { "type": "integer", "description": "Companies with any evidence for the technology." }, "jobs": { "type": "integer", "description": "Postings that named it." } } } } } }, "TechnologyListResponse": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "metadata": { "type": "object", "properties": { "total_results": { "type": "integer" }, "limit": { "type": "integer" }, "page": { "type": "integer" } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "technology": { "$ref": "#/components/schemas/Technology" }, "companies": { "type": "integer" }, "jobs": { "type": "integer" }, "first_date_found": { "type": "string", "nullable": true }, "last_date_found": { "type": "string", "nullable": true } } } } } }, "TechnologyCompany": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "tier": { "type": "string", "enum": [ "confirmed", "likely", "mentioned" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "jobs": { "type": "integer" }, "first_date_found": { "type": "string", "nullable": true }, "last_date_found": { "type": "string", "nullable": true } } }, "TechnologyDetailResponse": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "technology": { "$ref": "#/components/schemas/Technology" }, "companies": { "type": "integer" }, "jobs": { "type": "integer" }, "first_date_found": { "type": "string", "nullable": true }, "last_date_found": { "type": "string", "nullable": true }, "companies_by_tier": { "type": "object", "properties": { "confirmed": { "type": "integer" }, "likely": { "type": "integer" }, "mentioned": { "type": "integer" } } }, "top_countries": { "type": "array", "items": { "type": "string" } }, "top_occupations": { "type": "array", "items": { "type": "string" } }, "top_companies": { "type": "array", "items": { "$ref": "#/components/schemas/TechnologyCompany" } }, "recently_adopted": { "type": "array", "items": { "$ref": "#/components/schemas/TechnologyCompany" } }, "monthly_adoption": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "companies": { "type": "integer", "description": "Companies whose first posting naming it is in this month." }, "active_companies": { "type": "integer", "description": "Companies with a posting naming it in this month." }, "jobs": { "type": "integer" } } } } } }, "BillingCheckoutError": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_package", "bad_credits", "enterprise", "already_subscribed", "downgrade_requires_dashboard", "checkout_failed" ] }, "message": { "type": "string" }, "contact_url": { "type": "string", "format": "uri", "description": "enterprise only: where to arrange a plan above the largest package." }, "billing_url": { "type": "string", "format": "uri", "description": "downgrade_requires_dashboard only: the billing page where the account holder changes to a smaller package." } } }, "CompanyCandidate": { "type": "object", "description": "One company a typed name may mean: identity fields only, never a profile. verified is true when two independent sources agree on the domain, so GET /v1/companies/{domain} resolves it; an unverified candidate carries its best-known domain, or null.", "required": [ "key", "name", "domain", "jobs", "hq_country", "verified" ], "additionalProperties": false, "properties": { "key": { "type": "string", "description": "The company's id. Opens GET /v1/jobs/companies/{key} and matches company_key_or on job search." }, "name": { "type": "string", "description": "The company's name as its postings state it." }, "domain": { "type": "string", "nullable": true, "description": "Confirmed domain when verified is true; otherwise the best-known domain, or null." }, "jobs": { "type": "integer", "minimum": 0, "description": "Open postings currently shown for this company." }, "hq_country": { "type": "string", "nullable": true, "pattern": "^[A-Z]{2}$", "description": "Headquarters country as an ISO 3166-1 alpha-2 code, or null." }, "verified": { "type": "boolean", "description": "True when two independent sources agree on the domain." } } }, "CompanySuggestResponse": { "type": "object", "required": [ "query", "candidates" ], "properties": { "query": { "type": "string", "description": "The text that was matched, normalised." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyCandidate" }, "description": "Matching companies, best first; empty when nothing matches." } } }, "CompanyNotFoundResponse": { "type": "object", "description": "Sent with HTTP 404 by GET /v1/companies/{key} when no confirmed record matches, and by GET /v1/companies/{key}/technologies when the key names no company. The candidates are the companies the key may have meant; pick one and use its key, name or verified domain. A 404 costs nothing.", "required": [ "error", "next_step", "candidates" ], "properties": { "error": { "type": "string", "enum": [ "company_not_found" ] }, "next_step": { "type": "string", "description": "What to do with the candidates." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyCandidate" }, "description": "Companies whose name starts with the key, best first; may be empty. GET /v1/companies/{key} lists at most 5." }, "did_you_mean": { "type": "string", "nullable": true, "description": "Sent by GET /v1/companies/{key}: the best candidate as a key to retry with, its verified domain (\"okta.com\") or else its name; null when there are no candidates." } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error message, e.g. \"Invalid search filters: unknown filter: 'query'. Did you mean query -> job_title_or?\". Not a stable machine-readable code; match on the HTTP status instead. A few stack-scan errors carry a short identifier such as missing_domain or invalid_domain." }, "message": { "type": "string", "description": "Additional detail. Present on 402 quota responses; other errors carry only error." } } }, "RateLimitErrorResponse": { "type": "object", "required": [ "error" ], "description": "Sent with HTTP 429 when the per-second rate limit is exceeded. The response also carries Retry-After: 1 and the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers. A 429 costs no credit.", "properties": { "error": { "type": "string", "description": "Human-readable message: \"Rate limit exceeded\"." } } }, "HiringCompaniesRequest": { "type": "object", "description": "Every job search filter (combined with AND, as on job search), plus paging and sort for the companies behind the matching jobs. Unknown fields are rejected with HTTP 400.", "properties": { "job_title_or": { "type": "array", "items": { "type": "string" }, "maxItems": 60, "description": "Match jobs whose title contains any of these. At most 60." }, "job_title_not": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Exclude jobs whose title contains any of these. At most 100." }, "description_or": { "type": "array", "items": { "type": "string" }, "maxItems": 25, "description": "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. Words match whole: \"engineer\" does not match \"engineering\" or \"engineers\", so list each form you want (for example [\"engineer\", \"engineering\"]). At most 25." }, "description_phrase_or": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 25, "description": "Match jobs whose description contains any one of these exact phrases. The words must appear in this order and next to each other (any spaces or hyphens between them), and each phrase matches whole: \"LangGraph\" does not match \"LangGraphs\". Matching is case-insensitive, except that a phrase written entirely in capitals, such as \"MCP\" or \"E2B\", matches only in capitals, so \"mcp\" in a URL does not count. Use it for product, framework and tool names, where description_or would also match the words scattered apart. Given with description_or, a job must match both. At most 25." }, "description_not": { "type": "array", "items": { "type": "string" }, "maxItems": 25, "description": "Exclude jobs whose description contains every word of any one of these phrases, matched the same way as description_or: whole words, case-insensitive, in any order, not necessarily adjacent. At most 25." }, "job_country_code_or": { "type": "array", "items": { "type": "string" }, "description": "Match any of these ISO alpha-2 country codes, e.g. US, GB." }, "job_country_code_not": { "type": "array", "items": { "type": "string" }, "description": "Exclude these ISO alpha-2 country codes." }, "job_location_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "Match any of these seniority levels." }, "include_unlabeled_employment_type": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "ISIC Rev.4 industry divisions of the employer (2-digit, e.g. 62 = Computer programming and consultancy)." }, "region_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "full-time", "part-time", "contract", "temporary", "internship" ] }, "description": "Match any of these employment types." }, "language_or": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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, francetravail. ATS (company career sites): greenhouse, workday, ashby, lever, workable, recruitee, personio, smartrecruiters, oracle, icims, successfactors, 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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Match any of these company names (partial / contains). At most 100." }, "company_technology_slug_or": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "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": { "type": "integer", "description": "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": { "type": "integer", "description": "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": { "type": "number", "minimum": 0, "description": "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": { "type": "number", "minimum": 0, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[0-9A-Za-z]{20}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[0-9]{1,20}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "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": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "Only jobs at companies headquartered outside these countries (ISO 3166-1 alpha-2). Companies with no known headquarters never match." }, "remote": { "type": "boolean", "description": "true for remote-only, false to exclude remote." }, "work_arrangement_or": { "type": "array", "items": { "type": "string", "enum": [ "remote", "hybrid", "onsite" ] }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "offers", "no", "citizenship_required" ] }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "integer", "minimum": 0, "description": "Only jobs whose applicant_count is at most this value. Only LinkedIn and CV-Library postings carry one, so this filter also drops every job without a count. On LinkedIn the value is a threshold from the posting's badge, not an exact count: 25 means 25 or fewer so far, 200 means more than 200, so 25 keeps the early-applicant postings." }, "has_recruiter_email": { "type": "boolean", "description": "true for only jobs with a recruiter contact email parsed from the posting, false for only jobs without one." }, "min_salary_usd": { "type": "integer", "minimum": 0, "description": "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": { "type": "integer", "minimum": 0, "maximum": 100, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employment_type", "seniority", "work_arrangement", "location", "occupation", "industry", "visa_sponsorship", "benefits", "company_size", "company_revenue", "salary", "language" ] }, "description": "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": { "type": "integer", "minimum": 1, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Only postings newer than this many days, at most 365. Leave it out for the whole corpus." }, "posted_at_gte": { "type": "string", "description": "Only postings on or after this date (YYYY-MM-DD, or an ISO 8601 datetime). Any other value is a 400." }, "posted_at_lte": { "type": "string", "description": "Only postings on or before this date (YYYY-MM-DD, or an ISO 8601 datetime). Any other value is a 400." }, "discovered_at_gte": { "type": "string", "description": "Only postings first discovered by JobsPipe at or after this UTC datetime (YYYY-MM-DD HH:MM:SS, or any ISO 8601 datetime; any other value is a 400). Tracks when we first saw the posting, not when it was posted. A posting can become searchable well after that time, so to poll for new jobs use delta_cursor, which cannot miss one." }, "limit": { "type": "integer", "minimum": 1, "description": "Companies to return, 25 by default, capped by your plan's page size." }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Companies to skip." }, "page": { "type": "integer", "minimum": 0, "description": "Page index (alternative to offset)." }, "cursor": { "type": "string", "description": "Opaque cursor from metadata.next_cursor." }, "status": { "type": "string", "enum": [ "active", "closed", "any" ], "default": "active", "description": "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": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "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." }, "company_name_not": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 100, "description": "Exclude jobs at any of these companies. 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 name also excludes the longer names it starts, followed by a space, so Amazon excludes Amazon Web Services but not Amazonia. A name ending in a legal suffix excludes only that company's own spellings: its whole form, as an exact name or a prefix, and the same name with its suffixes dropped, as an exact name, so Capital Group excludes Capital Group Companies and Capital Inc and keeps Capital One. One character or a bare generic word (The, SAS) alone is a 400: add its legal suffix (SAS Inc) to exclude that one company. A name is at most 200 characters and 400 bytes of UTF-8, about 130 characters in Chinese or Japanese. A name made only of punctuation excludes nothing. A job with no company name is never excluded. An excluded job is not returned and costs no credit. At most 100." }, "include_unknown_size": { "type": "boolean", "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employer", "agency", "broker" ] }, "description": "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": { "type": "array", "items": { "type": "string", "enum": [ "employer", "agency", "broker" ] }, "description": "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": { "type": "boolean", "description": "Include the total match count in metadata.total_results." }, "order_by": { "type": "string", "enum": [ "jobs", "last_posted", "employees" ], "default": "jobs", "description": "Sort by matching jobs, by newest matching posting, or by employees. Groups sort by their subtree." }, "parent": { "type": "string", "pattern": "^[A-Za-z0-9]{20}$", "description": "A group's LEI from a previous response: returns only that group's companies, as its children." }, "known_company_only": { "type": "boolean", "default": false, "description": "Only companies with a verified company profile. Leaves out job boards and aggregators that post jobs under their own name. Off by default." } }, "additionalProperties": false }, "HiringCompanyNode": { "type": "object", "description": "One row of the companies tree: a company with matching jobs, or a parent legal entity that groups companies. Children hold the same shape, nested to any depth.", "required": [ "key", "name", "jobs", "jobs_in_subtree", "depth", "has_children", "children" ], "properties": { "key": { "type": [ "string", "null" ], "description": "The company's id. Null for a parent entity with no matching jobs of its own; those rows are free." }, "name": { "type": "string", "description": "The company name as its job postings give it; for a parent entity, its legal name." }, "legal_name": { "type": [ "string", "null" ], "description": "The registered name of the legal entity the company was matched to." }, "lei": { "type": [ "string", "null" ], "description": "The legal entity's 20-character LEI. Use it with lei_or on job search to list the jobs of a whole group." }, "domain": { "type": [ "string", "null" ], "description": "The company's website domain, e.g. stripe.com." }, "website": { "type": [ "string", "null" ], "description": "The company's website, e.g. https://stripe.com." }, "logo": { "type": [ "string", "null" ], "description": "Logo URL." }, "linkedin_url": { "type": [ "string", "null" ], "description": "LinkedIn company page." }, "employee_count": { "type": [ "number", "null" ], "description": "Employees. A group row shows the group's own figure when known, never a subsidiary's." }, "revenue_usd": { "type": [ "number", "null" ], "description": "Annual revenue in US dollars, when known." }, "industry": { "type": [ "string", "null" ], "description": "Industry, when known." }, "hq_country": { "type": [ "string", "null" ], "description": "The country the company is headquartered in, ISO 3166-1 alpha-2, when known. Not where it is hiring: see countries. Filter on it with company_hq_country_or." }, "hq_city": { "type": [ "string", "null" ], "description": "Headquarters city, when known." }, "employer_type": { "type": [ "string", "null" ], "enum": [ "employer", "agency", "broker", null ], "description": "Who posts the jobs: the company itself, a staffing agency, or a job board republishing other companies' listings. Agencies and job boards are never placed inside a group. Exclude them with employer_type_not." }, "jobs": { "type": "integer", "description": "Matching jobs the company posted itself (0 for a parent entity)." }, "jobs_in_subtree": { "type": "integer", "description": "Matching jobs of this row and every row under it." }, "last_posted": { "type": [ "string", "null" ], "description": "Newest matching posting in this row's subtree, YYYY-MM-DD HH:MM:SS UTC." }, "countries": { "type": [ "integer", "null" ], "description": "Countries the company's matching jobs are in. Null for a parent entity." }, "depth": { "type": "integer", "description": "0 for a top-level row, then one more per level." }, "parent_lei": { "type": [ "string", "null" ], "description": "The LEI of the row above, or null at the top." }, "has_children": { "type": "boolean", "description": "Whether children holds rows." }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/HiringCompanyNode" }, "description": "The rows under this one." } } }, "HiringCompaniesResponse": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "type": "object", "properties": { "total_companies": { "type": [ "integer", "null" ], "description": "Companies with at least one matching job." }, "returned_companies": { "type": "integer", "description": "Companies on this page (parent entities not counted)." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null." }, "credits_charged": { "type": "integer", "description": "Credits this page cost, the same number the account's usage log shows. Companies already paid for this calendar month are free." }, "companies_already_paid": { "type": "integer", "description": "Companies on this page already paid for this calendar month, so free." } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HiringCompanyNode" } } } }, "CompanyProfileHeader": { "type": "object", "description": "Who the company is. A group page (g-) describes the legal entity and every company matched below it.", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "company", "group" ] }, "name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "lei": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "employee_count": { "type": [ "number", "null" ] }, "employee_range": { "oneOf": [ { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": [ "integer", "null" ], "description": "Null for an open top band, e.g. 10,001+." } }, "required": [ "min", "max" ] }, { "type": "null" } ], "description": "The size band the company states on its public profile, e.g. 1,001-5,000. Can differ from employee_count, which counts people." }, "revenue_usd": { "type": [ "number", "null" ] }, "industry": { "type": [ "string", "null" ] }, "hq_country": { "type": [ "string", "null" ], "description": "Where the company is headquartered (ISO 3166-1 alpha-2), not where it hires." }, "hq_city": { "type": [ "string", "null" ] }, "founded": { "type": [ "number", "null" ] }, "followers": { "type": [ "integer", "null" ], "description": "Followers of the company's public profile; null when unknown." }, "org_type": { "type": [ "string", "null" ], "description": "How the company describes itself on its public profile: \"Privately Held\", \"Public Company\", \"Nonprofit\"...; null when unknown." }, "open_jobs": { "type": "integer" }, "total_jobs": { "type": "integer", "description": "Every posting we have seen from the company, open or closed." }, "countries": { "type": "integer", "description": "Countries with open jobs." }, "last_posted": { "type": [ "string", "null" ] }, "group": { "oneOf": [ { "type": "object", "properties": { "lei": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] } } }, { "type": "null" } ], "description": "The top of the company's corporate group, when it is part of one." }, "parent_of": { "type": "integer", "description": "Entities below this one in its corporate group." }, "companies_matched": { "type": [ "integer", "null" ], "description": "Group pages: entities with job postings." } } }, "CompanyTrends": { "type": "object", "description": "How the company's hiring is changing. Every comparison is with all postings on the same job sources, so a source collecting more is never read as growth. History starts at history_since; weeks run Monday to Sunday and the current week is left out. Figures resting on too few postings are null.", "properties": { "history_since": { "type": "string", "format": "date" }, "share_index": { "type": "object", "description": "Weekly share of new postings on the company's job sources, indexed so 100 is its usual share.", "properties": { "weeks": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string", "format": "date" }, "company_new": { "type": "integer" }, "share_index": { "type": [ "number", "null" ] } } } }, "recent_vs_prior": { "type": [ "number", "null" ], "description": "The index of the last 4 full weeks minus the index of the 4 before, each pooled over its weeks, in index points." }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "momentum": { "type": "object", "description": "Growth in postings (last 4 full weeks over the 4 before) against the company's industry, and its percentile among the industry's companies.", "properties": { "industry": { "type": [ "string", "null" ] }, "company_growth": { "type": [ "number", "null" ] }, "industry_growth": { "type": [ "number", "null" ] }, "relative_momentum_pct": { "type": [ "number", "null" ], "description": "Percent above (+) or below (-) the industry's growth." }, "percentile": { "type": [ "number", "null" ] }, "peers": { "type": "integer" }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "function_mix": { "type": "object", "description": "Job functions of postings that carry one, last 4 weeks against the 4 before, beside the market's own change.", "properties": { "functions": { "type": "array", "items": { "type": "object", "properties": { "job_function": { "type": "string" }, "recent": { "type": "integer" }, "prior": { "type": "integer" }, "share_recent": { "type": [ "number", "null" ] }, "share_prior": { "type": [ "number", "null" ] }, "delta_pp": { "type": [ "number", "null" ] }, "market_share_recent": { "type": [ "number", "null" ] }, "market_delta_pp": { "type": [ "number", "null" ] }, "relative_delta_pp": { "type": [ "number", "null" ], "description": "The company's change minus the market's, in percentage points." } } } }, "labelled_recent": { "type": "integer" }, "labelled_prior": { "type": "integer" }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "ai_intensity": { "type": "object", "description": "Share of postings that are AI work, against the market.", "properties": { "weeks": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string", "format": "date" }, "postings": { "type": "integer" }, "ai_postings": { "type": "integer" }, "ai_pct": { "type": [ "number", "null" ] }, "market_ai_pct": { "type": [ "number", "null" ] } } } }, "ai_pct": { "type": [ "number", "null" ] }, "market_ai_pct": { "type": [ "number", "null" ] }, "intensity_x": { "type": [ "number", "null" ], "description": "The company's AI share over the market's; 15 = fifteen times." }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "seniority": { "type": "object", "description": "Seniority mix (entry, mid, senior, lead, exec) of postings that state one.", "properties": { "weeks": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string", "format": "date" }, "labelled": { "type": "integer" }, "shares": { "type": [ "object", "null" ], "properties": { "entry": { "type": "number" }, "mid": { "type": "number" }, "senior": { "type": "number" }, "lead": { "type": "number" }, "exec": { "type": "number" } } }, "market_senior_pct": { "type": [ "number", "null" ] } } } }, "senior_pct": { "type": [ "number", "null" ] }, "market_senior_pct": { "type": [ "number", "null" ] }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "footprint": { "type": "object", "description": "Where the open jobs are.", "properties": { "open_jobs": { "type": "integer" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "open_jobs": { "type": "integer" }, "share": { "type": "number", "description": "A fraction of the open jobs, 0 to 1 (0.467 = 46.7%); not a percent." } } } }, "metros": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "metro_code": { "type": "string" }, "open_jobs": { "type": "integer" }, "share": { "type": "number", "description": "A fraction of the open jobs, 0 to 1 (0.467 = 46.7%); not a percent." } } } }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "locations": { "type": "object", "description": "Places where hiring started in the last 4 weeks (only where we already covered the place steadily), and places with no recent openings (never \"closed\").", "properties": { "new_locations": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "metro_code": { "type": "string", "description": "An internal metro id; show metro_name to readers." }, "metro_name": { "type": [ "string", "null" ], "description": "The place's name; null when we have none." }, "first_seen": { "type": "string", "format": "date" }, "last_seen": { "type": "string", "format": "date" }, "open_jobs": { "type": "integer" }, "total_jobs": { "type": "integer" } } } }, "quiet_locations": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "metro_code": { "type": "string", "description": "An internal metro id; show metro_name to readers." }, "metro_name": { "type": [ "string", "null" ], "description": "The place's name; null when we have none." }, "first_seen": { "type": "string", "format": "date" }, "last_seen": { "type": "string", "format": "date" }, "open_jobs": { "type": "integer" }, "total_jobs": { "type": "integer" } } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "leadership": { "type": "object", "description": "Leadership roles posted in the last 60 days: director, VP, head of, general manager and C-level titles, and executive roles. Counts are postings; each title is listed once.", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "posted": { "type": "string", "format": "date" }, "title": { "type": "string" }, "job_function": { "type": [ "string", "null" ] }, "seniority": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "first_leader_in_function": { "type": "boolean" }, "postings": { "type": "integer", "description": "Postings with this title in the last 60 days." } } } }, "last_30d": { "type": "integer" }, "prior_30d": { "type": "integer" }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } } } }, "CompanyTechChanges": { "type": "object", "description": "Technologies new in the company's job postings, and those rising, fading or possibly dropped.", "properties": { "observed_days": { "type": [ "integer", "null" ], "description": "Days since the company's first posting naming a technology. NEW is shown from 45." }, "new_technologies": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "first_seen": { "type": "string", "format": "date" }, "jobs": { "type": "integer" }, "required_jobs": { "type": "integer" }, "title_jobs": { "type": "integer" } } } }, "trends": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "recent": { "type": "integer" }, "prior": { "type": "integer" }, "share_recent": { "type": [ "number", "null" ] }, "share_prior": { "type": [ "number", "null" ] }, "delta_pp": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "rising", "fading", "possibly_dropped", "steady" ] } } } }, "possibly_replaced": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "category": { "type": "string" } } } }, "sample": { "type": "object", "description": "How many postings the figure rests on. thin = too few, so the figure is null rather than a guess.", "properties": { "n": { "type": "integer" }, "thin": { "type": "boolean" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "CompanySubsidiaries": { "type": "object", "description": "The companies of the corporate group, with their recent hiring.", "properties": { "group": { "oneOf": [ { "type": "object", "properties": { "lei": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "entities": { "type": "array", "description": "Every legal entity of the group's subtree, matched to a company or not.", "items": { "type": "object", "properties": { "lei": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "parent_lei": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "Where the entity is headquartered (else registered), ISO 3166-1 alpha-2." }, "company_keys": { "type": "array", "items": { "type": "string" }, "description": "Keys of the companies matched to the entity; empty when it has no postings of its own." } } } }, "companies": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "lei": { "type": [ "string", "null" ] }, "legal_name": { "type": [ "string", "null" ] }, "open_jobs": { "type": "integer" }, "new_28d": { "type": "integer" }, "prev_28d": { "type": "integer" }, "share_recent": { "type": [ "number", "null" ] }, "share_prior": { "type": [ "number", "null" ] }, "top_functions": { "type": "array", "items": { "type": "string" } }, "top_countries": { "type": "array", "items": { "type": "string" } }, "first_posted": { "type": [ "string", "null" ] }, "last_posted": { "type": [ "string", "null" ] }, "badges": { "type": "array", "items": { "type": "string", "enum": [ "new_entity", "no_recent_postings" ] } } } } }, "entities_matched": { "type": "integer" }, "entities_total": { "type": "integer" }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." }, "affiliated": { "type": "array", "description": "The brands, subsidiaries and showcases the company itself lists on its public profile, beyond the registry tree.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": [ "string", "null" ], "description": "The affiliate's own company key when it is a company we know with postings; null otherwise." }, "kind": { "type": "string", "enum": [ "company", "showcase" ], "description": "A company page, or a showcase page for a product or brand." }, "industry": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "open_jobs": { "type": [ "integer", "null" ], "description": "Its open jobs when it is a company we know; null otherwise." } } } } } }, "CompanyFacts": { "type": "object", "description": "Facts about the company as a business: ownership, listing, funding rounds, acquisitions and officers. Null when none are known.", "properties": { "ownership": { "type": [ "string", "null" ], "description": "\"Private\", \"Public\", \"Nonprofit\"...; null when unknown." }, "ticker": { "type": [ "string", "null" ], "description": "The stock ticker when the company is listed." }, "funding_total_usd": { "type": [ "number", "null" ] }, "funding_round_count": { "type": [ "integer", "null" ] }, "last_funding_date": { "type": [ "string", "null" ], "description": "YYYY-MM; null when undated." }, "funding_rounds": { "type": "array", "description": "Newest first.", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "description": "YYYY-MM; null when undated." }, "amount_usd": { "type": [ "number", "null" ] }, "round": { "type": [ "string", "null" ], "description": "\"Series B\", \"Seed\", \"Debt\"...; null when unnamed." } } } }, "acquisition_count": { "type": [ "integer", "null" ] }, "acquisitions": { "type": "array", "description": "Companies acquired, newest first; the amount where it was disclosed.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "date": { "type": [ "string", "null" ], "description": "YYYY-MM; null when undated." }, "amount_usd": { "type": [ "number", "null" ] } } } }, "officers": { "type": "array", "description": "The top officers as the public record names them.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" } } } }, "as_of": { "type": [ "string", "null" ], "description": "The day these facts were last gathered (YYYY-MM-DD)." } } }, "CompanyOffices": { "type": "object", "description": "Where the company has offices, from its public profile. Null when it lists none.", "properties": { "offices": { "type": "array", "description": "The primary office first.", "items": { "type": "object", "properties": { "primary": { "type": "boolean", "description": "The headquarters, as the company marks it." }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 when it could be read; else the country as the company wrote it." } } } }, "countries": { "type": "array", "description": "Offices per country, most first.", "items": { "type": "object", "properties": { "country": { "type": "string" }, "offices": { "type": "integer" } } } }, "as_of": { "type": [ "string", "null" ], "description": "The day the offices were last read (YYYY-MM-DD)." } } }, "CompanyPeers": { "type": "object", "description": "Companies the company's public profile lists as similar, linked to their own pages when we know them. Null when it lists none.", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": [ "string", "null" ], "description": "The peer's company key when it is a company we know with postings; null otherwise." }, "industry": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "open_jobs": { "type": [ "integer", "null" ], "description": "Its open jobs when it is a company we know; null otherwise." } } } }, "as_of": { "type": [ "string", "null" ], "description": "The day the list was last read (YYYY-MM-DD)." } } }, "CompanyLayoffs": { "type": "object", "description": "US WARN Act layoff and closure notices that name the company, matched with confidence. An empty list means no matched notice, not that the company had no layoffs.", "properties": { "notices": { "type": "array", "description": "Newest first, up to 100.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The notice's id, as GET /v1/layoffs returns it." }, "notice_date": { "type": [ "string", "null" ], "format": "date", "description": "The day the notice was given." }, "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "The day the layoff or closure takes effect, when stated." }, "state": { "type": "string", "description": "Two-letter postal code of the state that published the notice." }, "city": { "type": [ "string", "null" ] }, "employees": { "type": [ "integer", "null" ], "description": "Employees affected, when stated." }, "kind": { "type": "string", "enum": [ "layoff", "closure", "unknown" ] } } } }, "last_12_months": { "type": "object", "description": "Notices dated in the last 12 months, and the employees they name (a notice without a count adds none).", "properties": { "notices": { "type": "integer" }, "employees": { "type": "integer" } } }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "CompanyHiringMonthly": { "type": "object", "description": "New and closed postings per calendar month, over the last 12 months the history covers.", "properties": { "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "YYYY-MM." }, "new_postings": { "type": "integer", "description": "Postings first shown in the month." }, "closed_postings": { "type": "integer", "description": "Postings that closed in the month." }, "partial": { "type": "boolean", "description": "The current month, still running." } } } }, "history_since": { "type": "string", "format": "date", "description": "The first day counted; no earlier month is listed." }, "caveat": { "type": "string", "description": "What the figure means and its limits; show it beside the figure." } } }, "CompanyProfileResponse": { "type": "object", "required": [ "key", "found", "metadata" ], "properties": { "key": { "type": "string" }, "found": { "type": "boolean" }, "header": { "oneOf": [ { "$ref": "#/components/schemas/CompanyProfileHeader" }, { "type": "null" } ] }, "trends": { "oneOf": [ { "$ref": "#/components/schemas/CompanyTrends" }, { "type": "null" } ] }, "subsidiaries": { "oneOf": [ { "$ref": "#/components/schemas/CompanySubsidiaries" }, { "type": "null" } ], "description": "The company's corporate group, and the brands and subsidiaries it lists itself. Null when it is in no known group and lists none." }, "tech_changes": { "oneOf": [ { "$ref": "#/components/schemas/CompanyTechChanges" }, { "type": "null" } ] }, "facts": { "oneOf": [ { "$ref": "#/components/schemas/CompanyFacts" }, { "type": "null" } ], "description": "Null when no facts about the company are known." }, "offices": { "oneOf": [ { "$ref": "#/components/schemas/CompanyOffices" }, { "type": "null" } ], "description": "Null when the company's public profile lists no offices." }, "peers": { "oneOf": [ { "$ref": "#/components/schemas/CompanyPeers" }, { "type": "null" } ], "description": "Null when the company's public profile lists no similar companies." }, "layoffs": { "oneOf": [ { "$ref": "#/components/schemas/CompanyLayoffs" }, { "type": "null" } ] }, "hiring_monthly": { "oneOf": [ { "$ref": "#/components/schemas/CompanyHiringMonthly" }, { "type": "null" } ] }, "metadata": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "string", "enum": [ "header", "trends", "subsidiaries", "tech_changes", "facts", "offices", "peers", "layoffs", "hiring_monthly" ] } }, "generated_at": { "type": "string", "format": "date-time" }, "failed": { "type": "array", "items": { "type": "string", "enum": [ "header", "trends", "subsidiaries", "tech_changes", "facts", "offices", "peers", "layoffs", "hiring_monthly" ] }, "description": "Sections that could not be computed this time; they are null." }, "credits_charged": { "type": "integer", "description": "Credits this page cost, the same number the account's usage log shows; 0 when the company was already paid for this calendar month." }, "companies_already_paid": { "type": "integer" } } } } }, "CompanySummaryResponse": { "type": "object", "required": [ "key", "date", "source", "bullets", "facts" ], "properties": { "key": { "type": "string" }, "date": { "type": "string", "format": "date", "description": "The UTC day the summary was written for; it is rewritten daily." }, "source": { "type": "string", "enum": [ "ai", "template" ], "description": "\"ai\" when written by a language model, \"template\" when built directly from the figures." }, "bullets": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "properties": { "audience": { "type": "string", "enum": [ "investor", "government", "sales" ] }, "text": { "type": "string" } } } }, "facts": { "type": "object", "description": "The figures the summary was written from, and the only numbers it contains." } } }, "LayoffNotice": { "type": "object", "required": [ "id", "state", "employer", "address", "city", "county", "zip", "notice_date", "effective_date", "employees", "kind", "company" ], "properties": { "id": { "type": "string", "description": "The notice's id; stable when the state amends the notice." }, "state": { "type": "string", "description": "Two-letter postal code of the state that published the notice." }, "employer": { "type": "string", "description": "The employer as named on the notice." }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "notice_date": { "type": [ "string", "null" ], "format": "date", "description": "The day the notice was given or received." }, "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "The day the layoff or closure takes effect, when stated." }, "employees": { "type": [ "integer", "null" ], "description": "Employees affected, when stated." }, "kind": { "type": "string", "enum": [ "layoff", "closure", "unknown" ], "description": "closure: the site or plant closes. unknown: the notice does not say." }, "company": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "description": "The company's key, for its company page or as company_key_or in job search." }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] } } }, { "type": "null" } ], "description": "The company the notice names, when it is matched to the company with confidence; null otherwise." } } }, "LayoffsResponse": { "type": "object", "required": [ "data", "metadata" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LayoffNotice" }, "description": "Newest notice first." }, "metadata": { "type": "object", "properties": { "total_results": { "type": "integer", "description": "Notices the filters match." }, "returned_results": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ], "description": "The offset of the next page; null on the last page." }, "credits_charged": { "type": "integer" }, "notices_already_paid": { "type": "integer", "description": "Notices on this page already paid for this calendar month, so free." }, "credits_remaining": { "type": "integer", "description": "Credits the account can still spend after this call. Absent for callers that are not metered." }, "credits_allowance": { "type": "integer", "description": "What credits_remaining is measured against: the monthly allowance, or Free's one-time grant." } } } } }, "LiveSource": { "type": "object", "required": [ "source", "kind", "label", "examples" ], "properties": { "source": { "type": "string", "description": "The value for {source} in POST /v1/live/{source}, e.g. \"greenhouse\" or \"linkedin\"." }, "kind": { "type": "string", "enum": [ "board", "search" ], "description": "board: the input is one company job board. search: the input is keywords and a location." }, "label": { "type": "string", "description": "The source's display name." }, "examples": { "type": "array", "items": { "type": "string" }, "description": "Example board URLs or slugs this source accepts." } } }, "LiveSourcesResponse": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/LiveSource" } } } }, "LiveBoardRequest": { "type": "object", "additionalProperties": false, "required": [ "board" ], "description": "For a source of kind board: fetch one company board.", "properties": { "board": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "The board, as its URL (\"https://job-boards.greenhouse.io/stripe\") or its bare slug (\"stripe\")." }, "max_jobs": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The most jobs to return across this call." }, "include_descriptions": { "type": "boolean", "default": true, "description": "Fetch each job's full description." }, "cursor": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Opaque. Send back the next_cursor of the previous response to continue the same board or search; null or absent starts from the beginning." } } }, "LiveSearchRequest": { "type": "object", "additionalProperties": false, "description": "For a source of kind search: run one search. A source that cannot apply a filter itself applies it to the title and location of what it returns instead.", "properties": { "keywords": { "type": [ "string", "null" ], "maxLength": 500, "description": "What to search for, e.g. \"data engineer\"." }, "location": { "type": [ "string", "null" ], "maxLength": 500, "description": "Where, e.g. \"Berlin, Germany\"." }, "posted_within_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365, "description": "Only jobs posted in the last N days." }, "remote": { "type": [ "boolean", "null" ], "description": "true for remote jobs only; null for no preference." }, "max_jobs": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "The most jobs to return across this call." }, "cursor": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Opaque. Send back the next_cursor of the previous response to continue the same board or search; null or absent starts from the beginning." } } }, "LiveFetchResponse": { "type": "object", "required": [ "data", "metadata", "errors" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" }, "description": "The jobs fetched, each the same Job object job search returns. Fields that need a posting's history are null on a live job: closed_at, closed_reason and ghost_score among them. technologies is never present." }, "metadata": { "type": "object", "required": [ "source", "board", "returned", "next_cursor" ], "properties": { "source": { "type": "string" }, "board": { "type": [ "string", "null" ], "description": "The board's slug as the source knows it; null for a search." }, "returned": { "type": "integer", "description": "How many jobs are in data." }, "next_cursor": { "type": [ "string", "null" ], "description": "Non-null when there is more: send it back as cursor, with the same body, for the next part. null when done." } } }, "errors": { "type": "array", "description": "Problems that did not fail the call, e.g. { \"code\": \"board_not_found\" } with an empty data.", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "LiveErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "live_not_enabled", "unknown_source", "bad_board", "bad_request", "busy", "upstream_unavailable", "timeout" ], "description": "A stable code; branch on it." }, "message": { "type": "string", "description": "Detail for bad_board and bad_request." }, "retry_after": { "type": "integer", "description": "Seconds to wait before retrying. Present on busy." } } } } }, "tags": [ { "name": "Account", "description": "The calling account, its credits, and feedback on the data." }, { "name": "Billing", "description": "Buy a package or credits." } ] }