NPI Search

Search the NPPES National Provider Identifier registry by name, NPI, taxonomy, or location

The NPI Search API queries the local copy of the CMS NPPES NPI Registry populated weekly from the official bulk dissemination file, and falls back to the live NPPES API when needed.

Backend	When it’s used	Filters supported
Local DB (nppes_records)	Default. Loaded from the weekly NPPES dissemination CSV.	All filters below, including taxonomy_code and facility_ccn (which the live API can’t do).
Live NPPES	Automatic fallback when local search returns 0 results, or explicit opt-in via ?live=true.	The CMS-supported subset (no taxonomy_code, no facility_ccn).

This means brand-new NPIs that haven’t reached our copy yet are still discoverable, while bulk analytical queries (“every cardiologist in Kansas”) run against fast local indexes instead of rate-limited CMS endpoints.

Search providers

Search by any combination of name, state, city, taxonomy, or organization:

By Name

curl "https://api-dev.rcintell.com/v1/npi/search?first_name=Jane&last_name=Smith&state=KS" \
  -H "X-API-Key: kp_test_..."

Search parameters

Parameter	Type	Description
first_name	string	Provider first name (exact match against local DB)
last_name	string	Provider last name (exact match against local DB)
organization_name	string	Organization name (substring match)
state	string	Two-letter state code (e.g. KS). Matched against the practice address.
city	string	City name
taxonomy_code	string	NUCC taxonomy code (e.g. 207RC0000X). Local DB only.
taxonomy_description	string	Taxonomy description (substring match)
postal_code	string	ZIP code (prefix match)
enumeration_type	enum	NPI-1 (individual) or NPI-2 (organization)
facility_ccn	string	Filter to providers/orgs whose NPI is registered against a specific facility CCN. Local DB only. Useful for “show me the org NPI for facility 280003”.
live	bool	If true, bypass the local table and hit the live CMS NPPES API directly. Defaults to false.
limit	int	Max results (default 20, max 200)
skip	int	Pagination offset

Response

{
  "count": 2,
  "results": [
    {
      "npi": "1234567890",
      "entity_type": "NPI-1",
      "provider_name": "Jane Smith, MD",
      "first_name": "Jane",
      "last_name": "Smith",
      "organization_name": null,
      "taxonomies": [
        {
          "code": "207R00000X",
          "description": "Internal Medicine",
          "primary": true,
          "state": "KS",
          "license": "12345"
        }
      ],
      "addresses": [
        {
          "address_purpose": "LOCATION",
          "address_1": "123 Medical Center Dr",
          "city": "Topeka",
          "state": "KS",
          "postal_code": "66604",
          "telephone_number": "7855550100"
        }
      ],
      "enumeration_date": "2005-05-23",
      "last_updated": "2024-01-15",
      "status": "A"
    }
  ]
}

Look up a single NPI

Retrieve the full record for a specific NPI number:

curl "https://api-dev.rcintell.com/v1/npi/1234567890" \
  -H "X-API-Key: kp_test_..."

Response

{
  "npi": "1234567890",
  "entity_type": "NPI-1",
  "provider_name": "Jane Smith, MD",
  "first_name": "Jane",
  "last_name": "Smith",
  "organization_name": null,
  "taxonomies": [...],
  "addresses": [...],
  "enumeration_date": "2005-05-23",
  "last_updated": "2024-01-15",
  "status": "A"
}

Caching & freshness

The local copy is refreshed weekly from the CMS dissemination file. For a live CMS call, pass ?live=true. Live responses are cached for 24 hours.

How it works

Client → RCI Platform
  ├─ live=false (default): SQL on nppes_records (fast, supports taxonomy_code + facility_ccn)
  │   └─ if 0 results → Live CMS NPPES API v2.1 → Redis cache → return
  └─ live=true: skip local, query CMS NPPES API v2.1 directly → Redis cache → return

Common taxonomy codes

Code	Specialty
207R00000X	Internal Medicine
207Q00000X	Family Medicine
2084P0800X	Psychiatry
208600000X	Surgery
207X00000X	Orthopedic Surgery
261QM0801X	Critical Access Hospital
282N00000X	General Acute Care Hospital
207RC0000X	Cardiovascular Disease

Rate limits

NPI search follows the same rate limits as other authenticated endpoints (configurable per tenant). The Redis cache means repeated queries don’t count against rate limits after the first call.