Read a company's open jobs from its public job board. Give it a Greenhouse, Ashby, Lever or Workable board URL (or
vendor:slug) and get every open job back in one shape, whichever vendor hosts the board. No API key, no account,
no browser: each board is one request to the vendor's public job-board endpoint.
https://jobs.lever.co/acme -> {"vendor": "lever", "all_open_jobs_count": 12, "jobs": [{"title": ..., "country": "US", ...}]}
pip install hiring-signals-collectorPython 3.9 or newer. One dependency: httpx.
Not on PyPI yet. Until the first release, install from a checkout:
pip install .
hiring-signals https://job-boards.greenhouse.io/acme ashby:acmefrom hiring_signals_collector import read_board
board = read_board("https://jobs.lever.co/acme")
print(board["status"], board["all_open_jobs_count"])
for job in board["jobs"]:
print(job["title"], job["location_text"], job["country"], job["posted_at"])| Vendor | Accepted inputs | Endpoint read |
|---|---|---|
| Greenhouse | boards.greenhouse.io/<slug>, job-boards.greenhouse.io/<slug>, embed URLs (?for=<slug>), greenhouse:<slug> |
boards-api.greenhouse.io/v1/boards/<slug>/jobs?content=true |
| Ashby | jobs.ashbyhq.com/<slug>, ashby:<slug> |
api.ashbyhq.com/posting-api/job-board/<slug> |
| Lever | jobs.lever.co/<slug>, jobs.eu.lever.co/<slug>, lever:<slug>, lever-eu:<slug> |
api.lever.co/v0/postings/<slug>?mode=json (EU: api.eu.lever.co) |
| Workable | apply.workable.com/<slug>/, <slug>.workable.com, workable:<slug> |
apply.workable.com/api/v1/widget/accounts/<slug>?details=true |
The vendors' own API URLs are accepted too. The library does not look for a board on a company's website: you give the board.
hiring-signals [BOARD ...] [-f FILE] [--vendor greenhouse|ashby|lever|workable] [--format json|jsonl|csv]
[--jobs] [-o OUTPUT] [--no-descriptions] [--proxy URL] [--timeout S] [--fail-on-error] [--version]
BOARDis a board URL orvendor:slug. With--vendor, bare slugs are accepted (--vendor lever acme).-f boards.txtreads one board per line (#starts a comment);-f -reads stdin.--format json(default) writes one array;jsonlone line per board as soon as it is read;csvone row per job.--jobswrites one row per job (withvendor,board_slug,board_url,company_namein front) instead of one record per board. CSV is always one row per job; cells starting with=,+,-or@get a leading'.--no-descriptionsasks for the lighter job lists (nodescription_excerpt; Greenhousedepartmentstays empty, because Greenhouse sends departments only with descriptions).--proxy URL(or theHIRING_SIGNALS_PROXYenvironment variable) sends every request through your proxy, for examplehttp://user:pass@host:port. Without it, httpx uses the usualHTTPS_PROXYvariables if set.- Boards that could not be read are listed on stderr. Exit code 0 when the run finished, 1 with
--fail-on-errorwhen any board was notokorempty, 2 for usage errors.
hiring-signals -f boards.txt --format csv -o jobs.csv
hiring-signals --vendor workable acme --format jsonl --jobsfrom hiring_signals_collector import BoardRef, JobBoardReader, flatten, read_board, read_boards
read_board("greenhouse:acme") # one board, one record
read_board("acme", vendor="ashby", descriptions=False)
read_boards(["lever:acme", "https://apply.workable.com/acme/"], proxy="http://user:pass@host:port")
# Reuse one reader (one HTTP client, per-vendor spacing kept across calls).
with JobBoardReader(timeout=30) as reader:
for record in reader.read_many(["lever:acme", BoardRef("lever", "acme", eu=True)]):
for row in flatten(record): # one dict per job, board fields in front
print(row["company_name"], row["title"])JobBoardReader settings (all optional): proxy, timeout (seconds per network step, default 30),
descriptions (default True), min_interval ({vendor: seconds} between request starts, see Limits),
retry (default True: one retry), user_agent. A reader is not thread-safe; use one per thread.
parse_board(value, vendor=None) and parse_board_url(url) turn inputs into a BoardRef without any request.
One record per board. Every key is always present; null means "not known".
{
"input": "https://jobs.lever.co/acme",
"vendor": "lever",
"board_slug": "acme",
"board_url": "https://jobs.lever.co/acme",
"company_name": null,
"status": "ok",
"http_status": 200,
"error": null,
"all_open_jobs_count": 1,
"fetched_at": "2026-11-14T10:00:00Z",
"jobs": [
{
"job_id": "6f1c2a3b-0000-4000-8000-000000000001",
"title": "Sales Development Representative",
"url": "https://jobs.lever.co/acme/6f1c2a3b-0000-4000-8000-000000000001",
"department": "Revenue",
"team": "Sales / GTM",
"location_text": "New York, NY | Boston, MA",
"country": "US",
"us_state": "NY",
"city": "New York",
"remote": false,
"employment_type": "Full-time",
"posted_at": "2026-09-29",
"description_excerpt": "Book meetings for the sales team. What you will do Prospect Qualify ..."
}
]
}(Synthetic example.)
| Field | Meaning |
|---|---|
company_name |
the name in the vendor's reply: Greenhouse and Workable send one; Ashby and Lever job lists do not (null) |
status |
ok (jobs found), empty (the board exists, no open jobs), not_found (HTTP 404/410), rate_limited (HTTP 429), blocked (HTTP 401/403), error (other HTTP status, network error, or a reply that is not a job list), invalid_input (not a board URL or vendor:slug; no request made) |
all_open_jobs_count |
open jobs on the board (Ashby jobs marked unlisted are left out; Workable rows repeated per location are merged) |
job_id |
the vendor's job id (Workable: the shortcode) |
department, team |
as the vendor files them (Workable function is team) |
location_text |
the vendor's location text; several locations joined with | |
country |
two-letter code; vendor country fields win over the text; US when any location is in the US |
us_state, city |
first US state / first city found (state only for US jobs) |
remote |
the vendor marks the job remote, or the location text says so |
employment_type |
as the vendor writes it (Full-time, FullTime, Contract ...) |
posted_at |
first publish date (YYYY-MM-DD, UTC): Greenhouse first_published, Lever createdAt, Ashby publishedAt, Workable published_on (else created_at). Greenhouse updated_at is never used, so some Greenhouse jobs have null |
description_excerpt |
the first 600 characters of the job text, plain text; null with descriptions=False |
Be polite and respect each site's terms. These are public endpoints that the vendors serve for career pages; read the boards you need, not whole vendors.
- Spacing. Requests to one vendor start at least this far apart: Greenhouse 0.2 s, Ashby 0.5 s, Lever 1 s
(Lever's robots.txt asks for a Crawl-delay of 1 second), Workable 4 s. Workable allows roughly 1,000 requests per
hour from one address and answers HTTP 429 beyond that; 4 s keeps a long run at about 900 per hour. You can raise
these with
min_interval; values under 1 s for Lever or 3.6 s for Workable are raised to that floor. - Retries. At most one retry, after a fixed 2-second wait, on a network error, HTTP 429 or 5xx. A 429 that asks
to wait more than 30 seconds is not retried; the board is reported
rate_limited. - One request per board. Big boards (hundreds of jobs with descriptions) can be several megabytes; use
--no-descriptionswhen you only need titles and locations. - No discovery. The library reads boards you name. It does not search for companies, guess board slugs or find boards on company websites.
- Location parsing is heuristic: it reads the vendor's structured fields first and the location text second.
Unusual spellings can give
nullfields. - Greenhouse boards hosted in the EU are read through the main
boards-api.greenhouse.iohost.
pip install -e ".[dev]"
pytest # offline tests with synthetic fixtures
pytest --run-live -k live -s # reads one real board per vendor (a few requests)The live test picks boards from HSC_LIVE_GREENHOUSE, HSC_LIVE_ASHBY, HSC_LIVE_LEVER, HSC_LIVE_WORKABLE if set.
MIT