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"

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"

# 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-list changes or new Form 5500 filings.
# 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 -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)

Responses & errors

• 200 — resolved entity / matches / segment rows (with confidence + per-field provenance).
• 401 invalid/missing key · 402 over quota / not entitled · 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.