Skip to content

About

Read a company's open jobs from its public job board: Greenhouse, Ashby, Lever or Workable. No API key, no account, no browser.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

hiring-signals-collector

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", ...}]}

Install

pip install hiring-signals-collector

Python 3.9 or newer. One dependency: httpx.

Not on PyPI yet. Until the first release, install from a checkout: pip install .

Quick start

hiring-signals https://job-boards.greenhouse.io/acme ashby:acme
from 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"])

Which boards

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.

Command line

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]
  • BOARD is a board URL or vendor:slug. With --vendor, bare slugs are accepted (--vendor lever acme).
  • -f boards.txt reads one board per line (# starts a comment); -f - reads stdin.
  • --format json (default) writes one array; jsonl one line per board as soon as it is read; csv one row per job.
  • --jobs writes one row per job (with vendor, board_slug, board_url, company_name in front) instead of one record per board. CSV is always one row per job; cells starting with =, +, - or @ get a leading '.
  • --no-descriptions asks for the lighter job lists (no description_excerpt; Greenhouse department stays empty, because Greenhouse sends departments only with descriptions).
  • --proxy URL (or the HIRING_SIGNALS_PROXY environment variable) sends every request through your proxy, for example http://user:pass@host:port. Without it, httpx uses the usual HTTPS_PROXY variables if set.
  • Boards that could not be read are listed on stderr. Exit code 0 when the run finished, 1 with --fail-on-error when any board was not ok or empty, 2 for usage errors.
hiring-signals -f boards.txt --format csv -o jobs.csv
hiring-signals --vendor workable acme --format jsonl --jobs

Python API

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

The record

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

Limits and politeness

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-descriptions when 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 null fields.
  • Greenhouse boards hosted in the EU are read through the main boards-api.greenhouse.io host.

Development

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.

License

MIT

About

Read a company's open jobs from its public job board: Greenhouse, Ashby, Lever or Workable. No API key, no account, no browser.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages