nppes_lookup_provider
Look up US healthcare providers by NPI or search by name, organization, taxonomy, city, or ZIP code. Get validated provider data including active status, addresses, and taxonomies from NPPES.
Instructions
Keyless CMS/HHS NPPES NPI Registry — every US healthcare provider (NPI-1 individual + NPI-2 organization). EXACT-NPI mode (when number supplied): NPI is CMS-Luhn-validated — typo'd NPI is invalid_input, NEVER a fake 'does not exist'; wire carries number+version ALONE — co-supplied filters are DROPPED from wire and checked CLIENT-SIDE (filterMatch:{field:bool} + filtersDropped) because NPPES AND-combines number+filters and a mismatch would falsely zero a real active provider. SEARCH mode: required-one of {first_name, last_name, organization_name, taxonomy_description, city, postal_code} (state + enumeration_type are REFINERS ONLY — rejected alone); trailing '*' wildcard needs ≥2 leading literal chars. Returns EXACT-mode { found, provider:{number, enumerationType, active, basic, taxonomies, addresses, practiceLocations, identifiers, otherNames, endpoints, createdEpoch, lastUpdatedEpoch}, filterMatch? } OR SEARCH { providers:[…] } + honest _meta. HONESTY: active = basic.status==='A'; epochs are ms numeric STRINGS → number|null; addresses[] and practiceLocations[] kept SEPARATE (a provider may appear in practiceLocations ONLY); NPPES exposes NO match total — full page → totalAvailable is a LOWER BOUND (totalIsLowerBound) + reach cap (limit ≤ 200, skip ≤ 1,000). Genuine {result_count:0} → honest found:false; {Errors:[…]} 200 body THROWS; 4xx/5xx/timeout THROW; count mismatch → schema_drift. ★NOT a fitness/exclusion/licensure/sanctions determination — cross-check SAM + OFAC; NPI-1 records may surface personal/home addresses + phone/fax verbatim.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Address city (a required-one criterion). e.g. 'Baltimore'. | |
| skip | No | 0-based pagination offset, 0..1000 (default 0). ★POLICY cap: this vetting tool reaches at most the first ~1,200 matches/query (a deliberate targeted-lookup boundary — NPPES itself no longer enforces a skip ceiling); skip > 1000 ⇒ invalid_input. Search mode only. | |
| limit | No | Providers per page, 1..200, default 10. NPPES silently clamps >200; this tool rejects it loudly. Search mode only. | |
| state | No | US state/territory 2-letter USPS code — a REFINER only (never sufficient alone ⇒ invalid_input; NPPES rejects 'state' as the sole criterion). e.g. 'MD'. | |
| number | No | Exact NPI — 10 digits (^\d{10}$). Triggers EXACT-NPI mode: the wire query carries number (+version) ALONE (any co-supplied filter is DROPPED from the wire and checked client-side, disclosed in data.filterMatch — NPPES AND-combines a number with filters, so a mismatched filter would falsely zero a real active provider). Also client-side CMS-Luhn-validated (Luhn over 80840+first-9): a typo'd NPI ⇒ invalid_input, NEVER a fake 'does not exist'. e.g. '1104130236'. | |
| last_name | No | Individual provider last name (a required-one criterion). Trailing '*' wildcard: ≥2 leading chars. e.g. 'Smith'. | |
| first_name | No | Individual provider first name (a required-one criterion). A trailing '*' wildcard needs ≥2 leading literal chars. e.g. 'John'. | |
| postal_code | No | Address postal/ZIP code (a required-one criterion; a prefix like '212' is allowed). e.g. '21218'. | |
| enumeration_type | No | REFINER only (NPI-1 = individual, NPI-2 = organization). Never sufficient alone (⇒ invalid_input) — must accompany a required criterion. | |
| organization_name | No | Organization (NPI-2) name (a required-one criterion). Trailing '*' wildcard: ≥2 leading chars. e.g. 'Mayo Clinic'. | |
| taxonomy_description | No | Provider taxonomy/specialty description (a required-one criterion). e.g. 'Internal Medicine'. |