DEV Community

Chin Ramamoorthi at VBC Risk Analytics
Chin Ramamoorthi at VBC Risk Analytics

Posted on

How to Look Up Healthcare Providers by NPI with an API (real-time NPPES data)

#api #data #programming #tutorial

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
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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" }]
}
Enter fullscreen mode Exit fullscreen mode

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"))
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (1)

Collapse
 
blackflowuk profile image
Black Flow •

Worth stressing that NPI registry data feeds credentialing and scheduling — but the chart still needs a stable internal provider key, since taxonomy and practice-location updates from NPPES do not map cleanly to every ambulatory roster.