Npi Search Providers
npi_search_providersSearch the NPPES NPI registry for individual practitioners and healthcare organizations by name, organization name, location, provider type, and specialty. Plain-language specialty terms (e.g. "cardiologist", "pediatric cardiologist") resolve through the bundled NUCC taxonomy; the top match's specialization or classification becomes taxonomy_description, and all resolved candidates are returned in metadata. Location belongs in the dedicated city/state/postal_code inputs, not inside specialty. Each provider row includes the NPI, name, primary specialty, city/state/ZIP, type, and active/deactivated status; the NPI is the input for npi_get_provider when the full record is needed. At least one search criterion is required, and the registry rejects state-only searches. For specialty searches, returned providers are limited to the requested city/state/postal_code even when the registry includes providers outside that location. The registry never reports a true match total and only the first 1200 matches are reachable, so broad queries are capped.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Practice-location city. | |
| skip | No | Results to skip for pagination (0–1000). Only the first 1200 matches are reachable; skip beyond 1000 silently returns the same window — narrow the query instead of paging further. | |
| limit | No | Maximum providers to return (1–200; the registry caps at 200). | |
| state | No | 2-letter state code (e.g. "WA"). The registry rejects state-only searches, so another criterion is required. A blank value is treated as omitted. | |
| last_name | No | Individual last name. Trailing wildcard "*" allowed with at least 2 leading characters. | |
| specialty | No | Plain-language specialty (e.g. "pediatric cardiologist"), resolved through the bundled NUCC taxonomy to exact descriptions before searching. The matched taxonomy is echoed in the result. Mutually exclusive with taxonomy_description. | |
| first_name | No | Individual first name. Trailing wildcard "*" allowed with at least 2 leading characters. | |
| name_search | No | One person's name. The first token becomes first_name and the last token becomes last_name; use first_name/last_name when middle names or multi-part surnames matter. | |
| postal_code | No | Practice-location postal/ZIP code (5 or 9 digits). | |
| provider_type | No | Restrict to individuals (NPI-1) or organizations (NPI-2). Omit to search both. | |
| organization_name | No | Organization name (implies provider_type organization). Trailing wildcard "*" allowed with at least 2 leading characters. | |
| taxonomy_description | No | Exact NUCC taxonomy description for direct passthrough — use when the taxonomy description is already known. Mutually exclusive with specialty. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of providers returned. | |
| notice | No | Guidance — pagination ceiling, page-size-not-total caveat, or how to broaden an empty result. | |
| providers | No | Matching provider rows (up to limit). | |
| truncated | No | True when the NPPES page contained at least cap providers before location constraints were applied; more may match even when shown is below cap. | |
| resolvedTaxonomies | No | Taxonomy candidates ranked for the specialty term. The first candidate supplies appliedTaxonomyDescription; a different candidate can be selected through taxonomy_description. | |
| appliedTaxonomyDescription | No | The exact NUCC specialization or classification used as the specialty filter. |