How to build targeted firm lists with KnowFirm Discover

Q: Is the preview free?

Yes. GET /v1/segments/preview returns a count and the first 25 rows at no credit cost.

Q: Can I export more than 10,000 rows?

The limit parameter caps at 10,000 per request. For larger datasets, split across multiple requests using different state or size filters.

Q: Which sources require a state filter?

nppes (healthcare providers) and irseobmf (nonprofits) require a state. usaspendingrecipients requires either a state or a minSize.

KnowFirm Discover lets you build targeted firm lists from 12 public-record data sources. Preview a filtered segment (free), then export the full dataset when you find what you need. This guide covers each source, filtering, and export.

How Discover works

Discover has two endpoints:

Preview (GET /v1/segments/preview) — returns a count and the first 25 rows. Free, not billed per row. Use this to explore what's available and refine your filters.
Export (POST /v1/segments/export) — returns up to 10,000 rows. Billed at 1 credit per returned row. Requires the Starter plan.

Available sources

Source key	What it covers	Key fields
`dol_form5500`	Benefits-plan sponsors	Participants, NAICS, phone
`dol_form5500_sf`	Small-plan sponsors	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)	Annual revenue, NTEE category
`usaspending_recipients`	Federal contractors	UEI, DUNS, federal award amount
`nppes`	Healthcare providers	NPI, taxonomy, phone
`cms_hospitals`	Hospitals	CCN, star rating
`cms_nursing_homes`	Nursing homes	CCN, beds, star rating, abuse flag
`cms_home_health`	Home health agencies	CCN, quality star
`cms_dialysis`	Dialysis facilities	CCN, dialysis stations

Filter parameters

source (required) — one of the source keys above
state — two-letter state code (required for nppes and irs_eo_bmf)
minSize — minimum size threshold (participants, assets, revenue, beds, or stations depending on the source; required for usaspending_recipients when no state is given)
industryPrefix — NAICS prefix for DOL sources, NTEE letter for nonprofits
filedSinceDays — only entities with filings in the last N days (DOL sources)
limit — max rows to return (preview caps at 25; export max 10,000)

Examples

Find large Texas banks

# Preview: how many FDIC banks in Texas have $1B+ in assets?
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=fdic_institutions&state=TX&minSize=1000000"

# Export the full list (billed per row)
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

Find education nonprofits in New York

# NTEE category B = education
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=irs_eo_bmf&state=NY&industryPrefix=B&minSize=1000000"

Find federal contractors with large awards

# USAspending recipients with $5M+ in federal awards
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=usaspending_recipients&minSize=5000000"

Find recent Form 5500 filers in California

# Benefits-plan sponsors that filed in the last 90 days, 100+ participants
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=dol_form5500&state=CA&minSize=100&filedSinceDays=90"

Healthcare providers in Texas

# NPPES providers (state is required for this source)
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/segments/preview?source=nppes&state=TX"

TypeScript SDK

import { KnowFirm } from "./knowfirm";

const kf = new KnowFirm({ apiKey: process.env.KNOWFIRM_KEY! });

// Preview a segment
const preview = await kf.segmentPreview({
  source: "fdic_institutions",
  state: "TX",
  minSize: 1_000_000,
});
console.log(`Found ${preview.count} banks, showing ${preview.rows?.length}`);

// Export when ready (billed per row)
const data = await kf.segmentExport({
  source: "fdic_institutions",
  state: "TX",
  minSize: 1_000_000,
  limit: 500,
});
console.log(`Exported ${data.rows?.length} rows`);

Tips

Start with preview: preview is free and shows you the count before you commit credits to an export.
Use filters to narrow: broad unfiltered queries can return thousands of rows. Narrow by state, size, or industry prefix first.
National scans are limited: some sources reject national scans (no state filter) to keep query times reasonable. NPPES and IRS nonprofits require a state.
Export limits: a single export can return up to 10,000 rows. For larger datasets, paginate by state or use narrower filters.
Prospecting use: Discover is for prospecting and account intelligence. It is not for FCRA-covered eligibility decisions.

FAQ

Is the preview free? Yes. GET /v1/segments/preview returns a count and the first 25 rows at no credit cost.

How much does export cost? 1 credit per returned row. A 500-row export costs 500 credits.

Can I export more than 10,000 rows? The limit parameter caps at 10,000 per request. For larger datasets, split across multiple requests using different state or size filters.

Which sources require a state filter? nppes (healthcare providers) and irs_eo_bmf (nonprofits) require a state. usaspending_recipients requires either a state or a minSize.

What plan do I need for export? Preview works on the Free plan. Export requires Starter or above.