NPIDB APInpidb.org ↗
Search and look up NPI registry data including provider profiles, organization details, and taxonomy codes via the NPIDB.org API. 4 endpoints.
What is the NPIDB API?
The NPIDB.org API exposes 4 endpoints for querying the National Provider Identifier registry, returning structured data on individual healthcare providers and organizations. Use search_providers_by_name to find providers by first name, last name, and state, or call get_provider_detail with a 10-digit NPI to retrieve address, phone, fax, taxonomy specialties, enumeration date, and credential fields in a single response.
curl -X GET 'https://api.parse.bot/scraper/0ff82378-40e5-4e7b-9050-94cfc095e1fd/search_providers_by_name?page=1&state=NY&last_name=Smith&first_name=John' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace npidb-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""NPIdb Healthcare Provider Lookup — search providers, drill into details, browse organizations and taxonomy."""
from parse_apis.NPIdb_org_API import NPIdb, ProviderNotFound
client = NPIdb()
# Search for providers by last name and state — limit caps total items fetched.
for provider in client.providers.search(last_name="Smith", state="NY", limit=3):
print(provider.name, provider.npi, provider.location)
# Drill down: take one provider and fetch full detail via the instance method.
provider = client.providers.search(last_name="Johnson", state="CA", limit=1).first()
if provider:
detail = provider.detail()
print(detail.name, detail.address, detail.phone)
for tax in detail.taxonomies:
print(tax.name, tax.code, tax.primary)
# Search organizations by name and state
for org in client.organizations.search(org_name="Medical Center", state="TX", limit=3):
print(org.name, org.npi, org.taxonomy)
# Browse taxonomy categories
for cat in client.taxonomy_categories.list(limit=5):
print(cat.name, cat.url)
# Typed error handling: catch ProviderNotFound on a bad NPI lookup.
try:
bad_detail = client.provider_details.get(npi="0000000000")
print(bad_detail.name)
except ProviderNotFound as exc:
print(f"Provider not found: NPI {exc.npi}")
print("exercised: providers.search / provider.detail / organizations.search / taxonomy_categories.list / provider_details.get")
Search for healthcare providers by first name, last name, and state. Returns paginated results with NPI numbers, credentials, locations, and taxonomy specialties. At least one of first_name, last_name, or state should be provided for meaningful results.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| state | string | Two-letter US state code (e.g., NY, CA, TX). |
| last_name | string | Provider last name to search for. |
| first_name | string | Provider first name to search for. |
{
"type": "object",
"fields": {
"items": "array of provider objects with npi, name, credentials, location, taxonomy, and detail_url",
"total": "integer total result count, or null if not displayed"
},
"sample": {
"data": {
"items": [
{
"npi": "1629318639",
"name": "AARON H SMITH",
"location": "ASTORIA, NY",
"taxonomy": "174400000X -Specialist",
"detail_url": "https://npidb.org/doctors/other_service/specialist_174400000x/1629318639.aspx?src=2",
"credentials": ""
}
],
"total": null
},
"status": "success"
}
}About the NPIDB API
Provider Search and Detail Lookup
The search_providers_by_name endpoint accepts first_name, last_name, and state (two-letter code) as optional filters and returns paginated arrays of provider objects. Each item includes npi, name, credentials, location, taxonomy, and a detail_url. The total field gives the overall result count when the source displays it, and is null otherwise. Pagination is controlled with the page parameter.
For full provider records, get_provider_detail takes a required npi string and returns a single structured object: name, address, phone, fax, and a details sub-object containing status, credentials, entity, enumeration_date, and last_updated. The taxonomies array lists each specialty with its name, code, and a primary boolean indicating the provider's primary classification.
Organization Search and Taxonomy Browsing
search_organizations_by_name works similarly to the provider search but targets healthcare organizations and medical groups. It requires org_name and optionally accepts state and page. Results follow the same item shape as provider search — npi, name, location, taxonomy, and detail_url — making it straightforward to handle both entity types with the same downstream logic.
list_taxonomy_codes takes no inputs and returns the full set of top-level NPI taxonomy categories, each with a name and a url. This is useful for enumerating available specialties before constructing searches or for building a reference taxonomy lookup in your application.
The NPIDB API is a managed, monitored endpoint for npidb.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when npidb.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official npidb.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify a provider's NPI number and active status before processing a healthcare claim.
- Build a physician directory filtered by state and specialty taxonomy using search_providers_by_name.
- Retrieve enumeration_date and last_updated fields to audit provider credential freshness in a compliance workflow.
- Look up organization NPI numbers for hospital systems and medical groups via search_organizations_by_name.
- Populate a taxonomy code reference table in a billing or EHR application using list_taxonomy_codes.
- Cross-reference provider phone and fax fields from get_provider_detail for outbound healthcare communications.
- Identify a provider's primary vs. secondary taxonomy specialties using the primary boolean in the taxonomies array.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does NPIDB.org have an official developer API?+
What does get_provider_detail return beyond basic contact info?+
name, address, phone, and fax, the endpoint returns a details object with status, credentials, entity type (individual vs. organization), enumeration_date, and last_updated. It also returns a taxonomies array where each entry includes the taxonomy code, human-readable name, and a primary boolean.Does the search return a reliable total result count?+
total field in search_providers_by_name results is populated when the source displays an overall count, but it is null when that count is not present. Applications should treat null as an indeterminate total rather than zero results, and use the page parameter to iterate through result pages to determine actual coverage.Can I look up a provider's license number or DEA number through this API?+
Is there a way to search providers by taxonomy code or specialty directly?+
list_taxonomy_codes enumerates categories but does not accept a code as a search filter. You can fork this API on Parse and revise it to add a taxonomy-based search endpoint.