Providers

OpenOpps v0.1 separates aggregate source adapters from job-capable provider adapters. Source adapters discover company boards; provider adapters detect or fetch postings from public board providers through the CLI and local SQLite state.

Python plugins can contribute additional source adapters and job providers through the openopps.plugins entry point group. Plugin capabilities appear in admin providers list and registry surfaces when loaded successfully, and load failures, disabled entries, allow-list filters, and conflicts are visible in plugins list. Installed plugins are discovered by default but only executed when their entry-point names are listed in OPENOPPS_PLUGIN_ALLOWED, unless OPENOPPS_PLUGIN_AUTOLOAD=true is set.

Use examples/plugins/minimal-openopps-plugin/ as the starting template for a packaged plugin with a pyproject.toml entry point.

Source Adapter Inventory

Source Catalog Sample

Non-VC Source Families

OpenOpps packages a small set of low-friction non-VC source families as source adapters, not job providers. These sources add company candidates and provenance metadata; they only become job-yielding after route detection, route probing, and provider job syncs find public job-capable routes.

Each packaged source includes taxonomy metadata such as providerType, coverageMode, accessType, licenseStatus, refreshCadence, and sourceAttribution in the source raw_metadata payload.

Support Levels

Job-Capable Providers

Detect-Only Providers

manatal and gem are preserved as board metadata until stable public fetching is added. Health reports group these under notCovered so they are visible without being treated as failed job syncs.

Public No-Auth Board Providers

Workable, Teamtailor, BambooHR, Rippling, and WP Job Manager are job-capable in v0.1 only through public unauthenticated board routes. Workable fetches list and per-job detail endpoints separately so raw_listing and raw_detail stay distinct for audit replay. BambooHR uses public careers endpoints such as /careers/list and /careers/{job_id}/detail; OpenOpps does not call authenticated BambooHR ATS APIs. WP Job Manager requires an explicit /wp-json/wp/v2/job-listings or /jm-ajax/get_listings/ endpoint and is not inferred from arbitrary WordPress sites.

Surplus field promotion

Greenhouse list responses with content=true promote metadata, requisition_id, language, and department/office hierarchy into provider_extras; prospect posts without internal_job_id are tagged posting_kind=prospect. See the S1–S4 surplus taxonomy in Data Model and openspec/changes/ingest-data-surplus/ for the full promotion manifest.

Provider Coverage

Provider coverage reports on the persisted SQLite dataset only. It does not perform live HTTP checks, source fetches, route probes, or job syncs. The deterministic smoke data proves the report shape; published real-world percentages must be measured from representative persisted source snapshots:

uv run openopps providers coverage
uv run openopps providers coverage --source a16z --provider any --json
uv run openopps providers coverage --source a16z --provider greenhouse
uv run openopps providers audit --source a16z --json
uv run openopps admin sources yield --json

Use coverage to answer whether the local data is complete enough for analysis. The JSON report includes source, board, route, and job counts; route counts by provider, support level, and last status; executable route counts; missing route metadata counts; duplicate route skips derived from the durable route registry; job counts by provider, source, and board; non-supported provider coverage; detect-only provider examples; boards with job-capable hints but no executable route; and boards with executable routes but zero persisted jobs.

admin sources yield reports source-family conversion from persisted records only: company candidates, canonical boards, provider hints, job-capable routes, route-ready routes, active job routes, duplicate board rate, active boards added, yield score, and taxonomy totals by provider type and access type.

Coverage also reports enrichment completeness percentages from deterministic provider-field mapping. These data-quality metrics cover posting URLs, apply URLs, locations, departments, descriptions, normalized compensation or salary, remote level, and employment type.

Route Probing

Some sources report provider hints without the public route token required for job fetching. Route probing tries candidate tokens derived from upstream slugs, remote ids, names, domains, and websites. Board keys such as a16z:acme are durable record identifiers, not provider route-token candidates.

uv run openopps admin providers probe-routes --source a16z --provider any --limit 25 --json

By default, probing only checks routes missing token or URL metadata and does not persist results. Use --include-existing to recheck existing routes and --apply to persist matched metadata.

Provider Health

Provider health samples source adapters and job-capable routes, then reports status counts:

uv run openopps providers health --source a16z --provider any --limit 25 --json

Health checks report active, empty, error, missing_route, not_covered, and duplicate route skips. Add --apply to persist source health under raw_metadata.health and board-provider route health under last_status.

Use provider health for live sampled HTTP status. Use provider coverage for offline persisted route coverage and enrichment quality. Use provider audit for candidate-provider adoption evidence.

Board Route Registry

The board_providers registry is the executable route layer between discovered boards and job sync. Use it before large syncs to confirm which routes are ready:

uv run openopps admin providers registry --provider any
uv run openopps admin providers registry --provider any --passed-probe-only --json
uv run openopps admin providers registry --provider any --include-missing --limit 50

Without --include-missing, admin providers registry skips job-capable hints that still lack executable metadata, such as an Ashby board token or complete Workday CXS route. --passed-probe-only narrows output to routes verified by a persisted admin providers probe-routes --apply result.

Use Explorer to inspect the generated static snapshot of persisted boards, board-provider routes, latest job rows, source/provider coverage, and data-quality signals.

Provider Limits

• Workday support is limited to public postings visible through careers sites; it is not official tenant API access.
• Ashby sync excludes isListed: false direct-link-only postings from normal output.
• Overlapping board records from multiple sources are merged by company domain. Board JSON includes source_keys and source_board_keys for every source currently represented by the canonical board, and provider requests are deduped before route probes and job syncs.
• Installed Python plugins are not sandboxed and run in the same process as OpenOpps.
• Use OPENOPPS_PLUGIN_ALLOWED to opt in trusted entry-point names before plugin code executes.
• Use OPENOPPS_PLUGIN_AUTOLOAD=true only in controlled environments where every installed openopps.plugins entry point is trusted.