> ## Documentation Index > Fetch the complete documentation index at: https://docs.rcintell.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://download.cms.gov/nppes/NPI_Files.html), and falls back to the live [NPPES API](https://npiregistry.cms.hhs.gov/) 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: ```bash By Name theme={null} curl "https://api-dev.rcintell.com/v1/npi/search?first_name=Jane&last_name=Smith&state=KS" \ -H "X-API-Key: kp_test_..." ``` ```bash By Organization theme={null} curl "https://api-dev.rcintell.com/v1/npi/search?organization_name=Stormont+Vail&state=KS" \ -H "X-API-Key: kp_test_..." ``` ```bash By Taxonomy theme={null} curl "https://api-dev.rcintell.com/v1/npi/search?taxonomy=207R00000X&state=KS" \ -H "X-API-Key: kp_test_..." ``` ```bash By City + State theme={null} curl "https://api-dev.rcintell.com/v1/npi/search?city=Topeka&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 ```json theme={null} { "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: ```bash theme={null} curl "https://api-dev.rcintell.com/v1/npi/1234567890" \ -H "X-API-Key: kp_test_..." ``` ### Response ```json theme={null} { "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. Trigger a manual refresh via the admin API: ```bash theme={null} curl -X POST "https://api-dev.rcintell.com/v1/admin/data/sources/NPPES%20NPI%20Registry%20%28bulk%29/sync" \ -H "X-API-Key: kp_test_..." ``` For live API calls (`?live=true` or local-miss fallback), responses are cached in Redis for 24h to minimise load on the CMS endpoint. ## 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.