If you build anything in healthcare — a provider directory, a credentialing tool, an EHR integration, or a claims pipeline — sooner or later you need to look up a provider by their NPI (National Provider Identifier) and get back clean, structured data.
In this tutorial we'll do exactly that with the NPI Registry API: look up a provider by NPI, search by name/taxonomy/location, and read the enriched fields it returns (taxonomy, practice locations, Medicare enrollment, PECOS and LEIE flags).
NPI Registry API vs. the free NPPES API. CMS publishes a free NPPES API at npiregistry.cms.hhs.gov — great for light, occasional use, but rate-limited and bare-bones. The commercial NPI Registry API used here adds enrichment (Medicare/PECOS/LEIE, similar providers) and a consistent JSON shape. Full comparison: NPPES API vs. NPI Registry API.
1. Get an API key
Sign up for a free trial and your API key arrives by email in seconds. You authenticate by sending it in an ApiKey header. Base URL:
https://restapi.npidataservices.com/api/v1
2. Your first request (cURL)
Look up the provider with NPI 1053500652:
curl -X GET \
'https://restapi.npidataservices.com/api/v1/findbyNPIId?NPIId=1053500652' \
-H 'accept: application/json' \
-H 'ApiKey: YOUR_API_KEY'
A trimmed response:
{
"npi": 1053500652,
"status": "success",
"entity_types": ["Organization"],
"organization": [{ "org_name": "LEVEL HOME HEALTH INC.", "auth_official_last_name": "DECKELMAN" }],
"taxonomy": [{ "taxonomy_code": "251E00000X", "taxonomy_desc": "Agencies:Home Health" }],
"location": [{ "addr_city": "PASADENA", "addr_state": "CA", "telephone": "9492060691" }],
"medicare_enrlmt": [{ "pac_id": "4284711805", "provider_type_dec": "PART A PROVIDER - HOME HEALTH AGENCY" }],
"entity_type": [{ "in_pecos": "Y", "in_leie": "N" }]
}
3. Python
import os, requests
API_KEY = os.environ.get("NPI_API_KEY", "YOUR_API_KEY")
BASE = "https://restapi.npidataservices.com/api/v1"
HEADERS = {"accept": "application/json", "ApiKey": API_KEY}
def find_by_npi(npi):
r = requests.get(f"{BASE}/findbyNPIId", params={"NPIId": npi}, headers=HEADERS, timeout=15)
r.raise_for_status()
return r.json()
data = find_by_npi("1053500652")
org = (data.get("organization") or [{}])[0]
tax = (data.get("taxonomy") or [{}])[0]
print(org.get("org_name"), "—", tax.get("taxonomy_desc"))
4. JavaScript (Node 18+)
const API_KEY = process.env.NPI_API_KEY || "YOUR_API_KEY";
const BASE = "https://restapi.npidataservices.com/api/v1";
async function findByNpi(npi) {
const res = await fetch(`${BASE}/findbyNPIId?NPIId=${npi}`, {
headers: { accept: "application/json", ApiKey: API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
const data = await findByNpi("1053500652");
console.log(data.organization?.[0]?.org_name, "—", data.taxonomy?.[0]?.taxonomy_desc);
5. The other search methods
Beyond NPI lookup, the NPI search API supports:
| Endpoint | Find providers by |
|---|---|
GET /findbyPACId |
PECOS PAC ID |
GET /findbyPACENRLId |
PECOS enrollment ID |
GET /findOrganizationByName |
organization name + ZIP |
GET /findIndividualProviderByName |
first/last name + ZIP |
GET /findProvidersByTaxonomyCode |
entity type + taxonomy + ZIP |
GET /findProviderByName |
org/last/first name + state |
Wrap-up
That's real-time NPI lookup and provider search in a few lines. Try every endpoint live in the interactive NPI Registry API documentation.
Built on NPPES data by VBC Risk Analytics.