NPI Registry (NPPES) API

Free NPPES NPI Registry API with no key: look up any US healthcare provider or organisation by NPI number, name, location or specialty taxonomy. Tested example included.

No API key requiredHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the NPI Registry (NPPES) API?

The NPI Registry API is the US government's free, key-free lookup for the National Provider Identifier system. It searches every registered US healthcare provider and organisation by NPI number, name, address, or specialty taxonomy, returning practice addresses, credentials and licensure details.

Every healthcare provider in the United States who transacts electronically must hold an NPI, a ten-digit identifier issued by CMS, and the registry of those identifiers is public by statute. That makes this API the authoritative source for provider directories, claims validation and credential checking — not a commercial aggregation but the actual registry.

Two practical characteristics shape how you query it. First, `version=2.1` is mandatory: omit it and the request fails outright. Second, the API is deliberately narrow about broad searches — it will not return everything, and requires enough criteria to constrain the result set, which is a privacy-conscious design rather than a bug. The taxonomy fields use NUCC Provider Taxonomy codes, a standardised specialty vocabulary, so filtering by specialty means using that vocabulary rather than free text.

Quick facts

Base URL: https://npiregistry.cms.hhs.gov/api
Authentication: No API key or account. It is a US federal public registry, published under statute.
Rate limit: No published hard limit. Results cap at 200 per request with a maximum skip of 1000, so it is not designed for bulk extraction — CMS publishes a full downloadable file for that.
Pricing: Free. US government public data.
CORS: Not enabled — call it from your server
Official docs: Read the docs

How to use the NPI Registry (NPPES) API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Find a paediatric provider in California

GET https://npiregistry.cms.hhs.gov/api/?version=2.1&state=CA&taxonomy_description=pediatrics&limit=1

curl

curl 'https://npiregistry.cms.hhs.gov/api/?version=2.1&state=CA&taxonomy_description=pediatrics&limit=1'

JavaScript (fetch)

const res = await fetch("https://npiregistry.cms.hhs.gov/api/?version=2.1&state=CA&taxonomy_description=pediatrics&limit=1");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://npiregistry.cms.hhs.gov/api/?version=2.1&state=CA&taxonomy_description=pediatrics&limit=1", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "result_count": 1,
  "results": [
    {
      "addresses": [
        {
          "address_1": "505 PARNASSUS AVE",
          "address_2": "ROOM L 767",
          "address_purpose": "MAILING",
          "address_type": "DOM",
          "city": "SAN FRANCISCO",
          "country_code": "US",
          "country_name": "United States",
          "fax_number": "415-353-1926",
          "postal_code": "941432204",
          "state": "CA",
          "telephone_number": "415-353-8564"
        },
        {
          "address_1": "505 PARNASSUS AVE",
          "address_2": "ROOM L 767",
          "address_purpose": "LOCATION",
          "address_type": "DOM",
          "city": "SAN FRANCISCO",
          "country_code": "US",
          "country_name": "United States",
          "fax_number": "415-353-1926",
          "postal_code": "941432204",
          "state": "CA",
          "telephone_number": "415-353-8564"
        }
      ],
      "basic": {
        "credential": "RN, CPNP",
        "enumeration_date": "2009-10-08",
        "first_name": "KATHRYN",
        "last_name": "AARONSON",
        "last_updated": "2009-10-08",
        "middle_name": "MARY FARRIS",
        "name_prefix": "--",
        "name_suffix": "--",
        "sex": "F",
        "sole_proprietor": "YES",
        "status": "A"
      },
      "created_epoch": "1255034048000",
      "endpoints": [],
      "enumeration_type": "NPI-1",
      "identifiers": [],
      "last_updated_epoch": "1255034048000",
      "number": "1992030951",
      "other_names": [],
      "practiceLocations": [],
      "taxonomies": [

Parameters

Parameter	Type	Required	Description
`version`	query	Required	API version. `2.1` is mandatory — the request fails without it. `2.1`
`number`	query	Optional	A specific ten-digit NPI number, which returns exactly one record. `1234567893`
`first_name / last_name`	query	Optional	Individual provider name. Supports a trailing `*` wildcard. `Smith`
`organization_name`	query	Optional	Organisation name, for NPI type 2 entities. `Mayo Clinic`
`state / city / postal_code`	query	Optional	Location filters. Two-letter state code. `CA`
`taxonomy_description`	query	Optional	Specialty from the NUCC Provider Taxonomy vocabulary. `pediatrics`
`limit / skip`	query	Optional	Page size up to 200, and offset up to 1000. `1`

Response fields

result_countinteger: How many records were returned. Zero with an empty `results` array is the normal miss — there is no error status.
results[].numberstring: The ten-digit NPI.
results[].enumeration_typestring: `NPI-1` for an individual provider, `NPI-2` for an organisation. They have quite different field sets.
results[].basicobject: Name, credentials, gender, sole proprietor status and enumeration date.
results[].addressesarray: Both MAILING and LOCATION addresses, distinguished by `address_purpose`. They frequently differ — the practice address is the LOCATION one.
results[].taxonomiesarray: NUCC specialty codes with descriptions, a primary flag, and state licence numbers.
results[].identifiersarray: Other identifiers such as Medicaid and Medicare numbers, where the provider supplied them.

What you can build with the NPI Registry (NPPES) API

Validate a provider's NPI before submitting a healthcare claim
Build a provider directory or find-a-doctor search
Verify specialty and state licensure for credentialing
Enrich patient records with authoritative provider details

Common errors and how to fix them

400

The `version` parameter was omitted.

Fix: `version=2.1` is mandatory on every request. This is the single most common failure.

result_count 0

No provider matched — including for a syntactically valid but unissued NPI.

Fix: Not an error. A test number like 1234567893 passes the checksum but is not assigned to anyone, so it returns an empty result set.

Too many criteria required

The API refuses overly broad searches.

Fix: This is deliberate privacy-conscious design. Add a state, city or taxonomy filter. For bulk work, use the full downloadable file CMS publishes instead.

NPI Registry (NPPES) API — frequently asked questions

Is the NPI Registry API free?

Yes, free with no API key or account. The NPI registry is a US federal public registry published under statute, so the data is public by design.

Why do I get a 400 error?

Almost certainly a missing `version` parameter. `version=2.1` is mandatory on every request, and omitting it fails outright rather than defaulting.

What is the difference between NPI-1 and NPI-2?

NPI-1 is an individual provider — a doctor, nurse or therapist — and NPI-2 is an organisation such as a hospital or group practice. They carry quite different field sets, so branch on `enumeration_type` before reading the record.

Why does a provider have two addresses?

Records carry both a MAILING and a LOCATION address, distinguished by `address_purpose`, and they frequently differ. The practice address patients would visit is the LOCATION one — using the mailing address for a directory is a common mistake.

Tools that pair with this API

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

CSV Cleaner & Deduplicator

Clean CSV online: remove duplicate rows, trim whitespace, drop empty rows and normalise the delimiter. See before/after counts — 100% in your browser.

NPI Registry (NPPES) is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.