Fail the build before you onboard an excluded provider

@fonteum/screen screens a list of NPIs against the excluded/compromised-anywhere check and exits non-zero on a hit — so a pull request, an onboarding job, or a deploy fails before a provider who is on a federal or state exclusion list slips through. Run it as a one-line npx command or drop in the GitHub Action. Every match carries its source, the public list URL to re-confirm against, the record date, and the methodology version.

Package: @fonteum/screen · REST base: https://api.fonteum.com/v1 · Demo key: pk_dx_sample (free, no signup)

• What it screens
• CLI
• GitHub Action
• Exit codes
• Auth + provenance

What it screens

For each NPI the CLI calls GET /api/v1/exclusions/{npi} and partitions the result into two clearly-distinct layers. The umbrella signal, compromised_anywhere, is true when either layer matches.

Screening aid — re-confirm any match against the primary source list before acting, and treat the absence of a match as “not found in the lists Fonteumcurrently holds” rather than a guarantee. Not a legal or credentialing certification.

CLI

No install required — npx fetches the package on first run. Pass NPIs as arguments, or point --file at a text list or a CSV (an npi column is used; otherwise every 10-digit token in the file is harvested).

# Screen one or more NPIs (no install — npx fetches the package)
npx @fonteum/screen 1245319599 1003002627

# Screen a file: plain text (one NPI per line) OR a CSV with an "npi" column
npx @fonteum/screen --file providers.csv

# Read NPIs from stdin
cat npis.txt | npx @fonteum/screen --file -

# Hard exclusions only — don't fail the build on a compromised-flag
npx @fonteum/screen --fail-on excluded --file providers.csv

# Machine-readable output for a downstream step
npx @fonteum/screen --json 1245319599

Example output

Each hit prints the source, the in-force date, the reason, and a provenance line; the run ends with a tally and a pass/fail verdict.

✗ 1932567890  EXCLUDED — OIG LEIE
    • OIG LEIE (federal) since 2015-03-01 — Conviction of program-related crimes
      provenance: oig-leie/v1 · snapshot 2026-06-01 · https://oig.hhs.gov/exclusions/exclusions_list.asp
✓ 1245319599  NO MATCH — no exclusion or compromised-flag in the lists Fonteum currently holds

2 screened · 1 excluded · 0 compromised-flag · 1 no-match · 0 error
FAIL — 1 hit(s) at fail-on=compromised

GitHub Action

The composite action wraps the same CLI. Add it to any workflow — onboarding gates, vendor-roster pull requests, pre-deploy checks. Inputs are passed through environment variables, not interpolated into the shell, so a crafted NPI string cannot inject commands.

# .github/workflows/provider-onboarding.yml
name: provider-onboarding
on: [pull_request]

jobs:
  screen-providers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Screen NPIs against the Fonteum exclusion check
        uses: Fonteum/screen@v1
        with:
          file: providers.csv          # text (one NPI/line) or CSV with an "npi" column
          fail-on: compromised          # excluded | compromised | none
          # api-key omitted -> free demo key (100 req/hour/IP).
          # For higher throughput store a pilot key as a secret:
          api-key: ${{ secrets.FONTEUM_API_KEY }}

Screen a fixed roster inline

      - name: Screen a fixed roster
        uses: Fonteum/screen@v1
        with:
          npis: "1245319599 1003002627"
          fail-on: excluded

Action inputs: npis, file, fail-on (excluded · compromised · none), api-key, api-base, concurrency, version, json. The runner only needs Node, which is present on ubuntu-latest.

Exit codes + fail-on

• 0 — no hits at the active --fail-on threshold.
• 1 — at least one hit, or an NPI could not be screened (network/API error). An NPI that cannot be checked is never treated as a pass.
• 2 — usage error (no NPIs, bad option, unreadable file).

--fail-on compromised (default) fails on an exclusion or a compromised-flag. --fail-on excluded fails only on a hard exclusion. --fail-on none reports without ever failing — useful for a non-blocking audit step.

Auth, rate limits, and provenance

• Free demo key. pk_dx_sample needs no signup and allows 100 REST requests/hour per IP. It is the default key.
• Higher throughput. Set FONTEUM_API_KEY or pass --api-key with a pilot key (fnt_…), sent as the X-Fonteum-Key header. Request one at /pilot-intake. In the Action, store it as a repo or org secret.
• Source on every match. Each match prints the issuing list, the public source URL to re-confirm against, the in-force date, the snapshot date, and the methodology version — drawn from the 14-tuple provenance contract. See the provenance contract.
• Read-only. The CLI only reads. It never mutates Fonteum data and never transmits your provider list anywhere but the screening endpoint.

See also

• Developer documentation hub
• REST API reference (OpenAPI)
• AI agent framework integrations
• 14-tuple provenance contract
• Methodology + limitations