ListRiver Business Data API

New and active U.S. businesses from official state business registries (Secretary of State filings), as JSON. New LLCs, corporations, nonprofits and partnerships, filtered by state, city, county, ZIP, NAICS industry, entity type, formation month, and whether a phone or email is on file.

• Free key: 500 records a month, no card needed: get one here
• Full documentation with a live "Try it" panel and examples in cURL, Python, JavaScript, C# and PHP: listriver.com/api-docs
• Python client: pip install listriver (source)
• OpenAPI 3 spec: openapi.yaml (import into Postman, Insomnia, Swagger UI or an AI agent)
• MCP server for Claude and other AI assistants, source in mcp/: uvx listriver-mcp

Typical uses: lead lists of brand-new businesses (formed this month), CRM enrichment, sales territory research, KYB and business verification, market sizing, and B2B prospecting by industry and place.

---

Quick start (2 minutes)

1. Create a free API account and click the link in the confirmation email.
2. On the API page, click Get my free API key and copy it.
3. Count a search (free), then pull the records:

# How many businesses formed in Miami in the last few months have a phone number? (free)
curl -H "X-Api-Key: YOUR_KEY" "https://listriver.com/api/data.ashx?action=count&states=FL&city=MIAMI&hasPhone=1&formedWithin=3"

# The first 10 of them
curl -H "X-Api-Key: YOUR_KEY" "https://listriver.com/api/data.ashx?action=records&states=FL&city=MIAMI&hasPhone=1&formedWithin=3&limit=10"

{
  "ok": true,
  "rows": [
    {
      "businessName": "ANGELI TRAVEL LLC",
      "entityType": "LIMITED LIABILITY COMPANY",
      "status": "ACTIVE",
      "formed": "2026-08",
      "registrationState": "FL",
      "stateFilingNumber": "L26000446708",
      "address": "2125 BISCAYNE BLVD, STE 204 #27572",
      "city": "MIAMI",
      "zip": "33137",
      "county": "MIAMI-DADE",
      "phone": "(786) 298-9566",
      "website": "HTTPS://ANGELITRAVELS.COM",
      "registeredAgent": "ULLOA SANCHEZ YUDELSA",
      "listriverId": "FL-L26000446708",
      "...": "35 fields in all"
    }
  ],
  "cursor": "FL.6604750",
  "resume": "FL.6604750"
}

Python

from listriver import Client

lr = Client("YOUR_KEY")
search = dict(states="FL", city="MIAMI", has_phone=True, formed_within=3)

print(lr.count(**search))                      # free
for business in lr.records(**search, max_records=100):
    print(business["businessName"], business["phone"])

More: examples/ (Python, JavaScript, curl) and the recipes (also C# and PHP).

---

MCP server (source in this repo)

This repository contains a Model Context Protocol server for ListRiver, written in Python: mcp/listriver_mcp/server.py (package mcp/, tests in mcp/tests/, MIT license). It runs over stdio and gives AI assistants (Claude Desktop, Claude Code, Cursor and other MCP clients) three tools:

Tool	What it does	Cost
list_states	States covered and their record counts	free
count_businesses	How many businesses match a search (state, city, county, ZIP, NAICS, entity type, formation month, phone/email on file)	free
search_businesses	The matching businesses, 25 by default and up to 100 per call, with a cursor for more	counts against your records

The server tells the assistant to count first and to fetch only what you need.

Install from PyPI (published from this repo's mcp/ folder) and add it to Claude Desktop (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "listriver": {
      "command": "uvx",
      "args": ["listriver-mcp"],
      "env": { "LISTRIVER_API_KEY": "lr_key_..." }
    }
  }
}

Or run it from source:

git clone https://github.com/ListRiver-LLC/listriver-api && cd listriver-api
pip install ./python ./mcp
LISTRIVER_API_KEY=lr_key_... listriver-mcp

# or with Docker, using the Dockerfile in this repo
docker build -t listriver-mcp .
docker run -i --rm -e LISTRIVER_API_KEY=lr_key_... listriver-mcp

Setup for other clients: mcp/README.md. Listed in the official MCP Registry as io.github.ListRiver-LLC/listriver.

---

Calls

Every call is an HTTPS GET to https://listriver.com/api/data.ashx with your key in the X-Api-Key header.

action	What it returns	Cost
states	Available states and record counts per formation window	free
count	How many records match your filters, per state	free (20 calls a minute)
records	Up to 1,000 matching records per call; pass cursor back for the next page	each record returned counts

Filters

records and count take the same filters. A record must match all of them; where a filter takes several comma-separated values, any one of them matches.

Parameter	Example	What it does
states	FL,TX	Registration states (leave out for all)
city	MIAMI,DORAL	Business city (needs states)
county	MIAMI-DADE or FL:MIAMI-DADE	Business county (needs states)
zip	33139,33140 or 331	5-digit ZIPs or 3-digit prefixes (needs states)
naics	23, 2361, 236115	NAICS industry prefix, 2 to 6 digits
entityType	LLC,CORP	LLC, CORP, LP, LLP, NONPROFIT, OTHER
hasPhone / hasEmail	1	Only businesses with a phone / email on file
formedWithin	3	Formed this month or in the N months before it
formedFrom / formedTo	2026-06 / 2026-09	Formed in this range of months
preset	recent (default), year, all	Shortcut windows

Formation dates are month-level (registries publish the month), so windows are whole calendar months.

Pricing

Plan	Records	Price
Free	500 / month	$0
Prepaid packs	5,000 / 7,500 / 10,000 (use within 12 months)	$50 / $75 / $100
Monthly plans	5,000 / 12,000 / 28,000 / 75,000 per month	$50 / $100 / $200 / $450
AWS Marketplace	larger volumes, billed on your AWS invoice	see listing

Only records returned count, and each record counts every time it is returned: overlapping or repeated searches count again. Count first (free), save the cursor or resume position to carry on later, and use listriverId to de-duplicate. Packs and plans are on your API page. Current prices are always on listriver.com/api-docs.

Keeping a feed up to date

Every records answer includes resume: the position after the last record returned, even on the last page. Save it per state, and pass it as cursor next time to get only the businesses ListRiver has added since. See examples/python/daily_feed.py.

Sample data

sample-data/ has a small sample of recent Florida formations (CSV and JSON, no emails) so you can judge the data before signing up. It is a sample, not a full file.

Data and terms

Records come from official state business registries, with addresses standardized and contact details, NAICS codes and EINs added where available. A field is null when the state doesn't publish it or ListRiver doesn't have it; nothing is estimated. Coverage and update schedules: listriver.com/methodology.

The code in this repository is MIT-licensed. The data (including sample-data/) is covered by the ListRiver API agreement: for your own business use, not for resale, and not for credit, insurance, employment or housing decisions.

Questions: support@listriver.com