API quickstart

Verify, enrich, and sanctions-screen any U.S. business in one call — or build targeted firm segments with Discover. Base URL https://api.knowfirm.com · auth header X-API-Key.

Sign in → create an API key Download the OpenAPI spec

curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/business?name=bank%20of%20america"
# round-trip an identifier from a Discover export — e.g. an FDIC bank by cert, or a public co by ticker:
curl -H "X-API-Key: $KNOWFIRM_KEY" "https://api.knowfirm.com/v1/business?cert=628"
curl -H "X-API-Key: $KNOWFIRM_KEY" "https://api.knowfirm.com/v1/business?ticker=AAPL"

curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/business/search?q=acme&limit=10"

# From a prior resolve's subjectKey — or the same identifier keys as GET /v1/business.
# Peers are a bounded Discover segment (Form 5500 NAICS + HQ state + size band).
# Missing NAICS/state → 200 with lookalikes:[] and an honest emptyReason (no scan).
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/business/similar?subjectKey=apple&limit=10"
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/business/similar?cik=320193"

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Example Trading Co"}' https://api.knowfirm.com/v1/screening

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"cik":"320193"},{"name":"bank of america"}]}' https://api.knowfirm.com/v1/enrich

# e.g. California benefits-plan sponsors with 100+ participants
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=dol_form5500&state=CA&minSize=100"

# e.g. New York education nonprofits (NTEE B) with $1M+ annual revenue
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=irs_eo_bmf&state=NY&industryPrefix=B&minSize=1000000"

# Public spending recipients — UEI (and DUNS when present), federal award amount.
# Not a SAM.gov exclusions or current-registration product. National scans are rejected.
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=usaspending_recipients&state=VA&minSize=1000000"
# amount-only also works:
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=usaspending_recipients&minSize=5000000"

# CMS public-file provider identity (NPI / taxonomy / phone when published).
# KYB / firmographic matching — not treatment, payment, or clinician marketing.
# National scans are rejected (9s query budget).
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=nppes&state=TX"

# Public CMS Care Compare lists. State is optional (national scans are small).
# Ratings / beds / abuse flag are labelled honestly — not FCRA eligibility data.
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=cms_hospitals&state=TX"
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=cms_nursing_homes&state=CA&minSize=50"

# e.g. Texas banks with $1B+ in assets — up to 'limit' rows
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"source":"fdic_institutions","state":"TX","minSize":1000000,"limit":500}' \
  https://api.knowfirm.com/v1/segments/export

# Watch by name (or subject_key): screening, new Form 5500, GLEIF lapse, or CFPB complaint spike.
# new_entity watches a SOURCE (fdic_institutions | ncua_credit_unions), not a company — subject_key only.
# gleif_lapse needs a subject that already has an LEI (404 otherwise).
# complaint_spike: 7-day window, 2× previous count, min 5. Informational — not FCRA.
# Re-checked nightly; alerts go to email + your webhook. 1 credit/month per active watch.
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"name":"acme corp","kind":"screening"}' https://api.knowfirm.com/v1/watch
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"name":"apple inc","kind":"gleif_lapse"}' https://api.knowfirm.com/v1/watch
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"name":"wells fargo","kind":"complaint_spike"}' https://api.knowfirm.com/v1/watch
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" -H "Content-Type: application/json" \
  -d '{"subject_key":"fdic_institutions","kind":"new_entity"}' https://api.knowfirm.com/v1/watch
curl -H "X-API-Key: $KNOWFIRM_KEY" https://api.knowfirm.com/v1/watch          # list
curl -X DELETE -H "X-API-Key: $KNOWFIRM_KEY" "https://api.knowfirm.com/v1/watch?id=<watch_id>"

Discover sources

Segment endpoints filter one public source by state, minSize, industryPrefix (NAICS on DOL sources, NTEE on nonprofits), and filedSinceDays (DOL sources). Preview is one call; export is billed per returned row and requires the Starter plan.

• dol_form5500 — Benefits-plan sponsors (Form 5500) — participants, NAICS, phone
• dol_form5500_sf — Small-plan sponsors (Form 5500-SF) — participants, NAICS, phone
• fdic_institutions — FDIC-insured banks — assets, state
• ncua_credit_unions — Credit unions (NCUA) — assets, state, phone
• fmcsa_carriers — Motor carriers (FMCSA) — power units, phone, email
• irs_eo_bmf — Nonprofits (IRS exempt organizations) — annual revenue, NTEE category (state filter required)
• usaspending_recipients — Federal contractors (USAspending recipients) — UEI, DUNS when present, federal award amount (state or minSize required; not SAM exclusions)
• nppes — Healthcare providers (NPPES) — NPI, taxonomy/phone when published (state required; KYB / firmographic matching, not clinician marketing)
• cms_hospitals — Hospitals (CMS Care Compare) — CCN, optional state, overall star rating when published (no beds; not FCRA)
• cms_nursing_homes — Nursing homes (CMS Care Compare) — CCN, certified beds (minSize), overall star rating, abuse flag (public quality icon, not a consumer report)
• cms_home_health — Home health agencies (CMS Care Compare) — CCN, optional state, quality-of-patient-care star (no beds)
• cms_dialysis — Dialysis facilities (CMS Care Compare) — CCN, dialysis stations (minSize); five-star key is empty on the current snapshot

Responses & errors

• 200 — resolved entity / matches / segment rows (with confidence + per-field provenance). Lookup may include optional complaintRisk (bounded CFPB company-level counts; informational, not a consumer report, not a creditworthiness score).
• 401 invalid/missing key · 402 over quota / not entitled · 403 ip_not_allowed (key locked to CIDRs) · 403 scope_denied (key locked to other operationIds) · 429 rate limited · 404 no match · 400 bad input (never billed).
• Failed lookups and over-quota calls are not billed; enrich bills per resolved record and segment export bills per returned row; your usage ledger is authoritative.