A developer inspecting a JSON provider record returned from the NPI Registry API
NPI REGISTRY API

How to Build with the NPI Registry API

Jul 23, 2026· 8 min read ·Data & analytics ·NPI Data Services

Almost every product that touches US healthcare eventually needs the same thing: given a provider, confirm they are real and pull their current details. The natural key is the National Provider Identifier, and the natural instinct is to hit an API. That is where most teams meet the NPI Registry API for the first time, ship a quick integration against the free public endpoint, and then discover a month later that it does not behave the way a production dependency should.

This guide is the thing I wish someone had handed me before that first integration: what the API is, exactly where the free version stops, and the decisions that keep your provider lookups from breaking as you scale.

What the NPI Registry API is

The NPI is a ten-digit identifier that the Centers for Medicare & Medicaid Services (CMS) assigns to covered health care providers. It is a HIPAA Administrative Simplification standard, and it is the single identifier that shows up on claims, in EHRs, and across payer systems (CMS Data Dissemination).

Behind the identifier is NPPES, the National Plan and Provider Enumeration System. CMS exposes the FOIA-disclosable portion of NPPES two ways: a downloadable file, and a query-only web service. That web service is the NPI Registry API — currently NPPES Read API version 2.1 (NPPES NPI Registry API). CMS states plainly that the Registry "is updated daily" and that there is "no charge to view the data" (CMS Data Dissemination).

So the good news up front: there is a free, official, government-run API for provider data, and you do not need an account or a key to call it. The rest of this guide is about the fine print.

A request that works

The API is a plain HTTPS GET that returns JSON. The one non-obvious requirement is that version is mandatory — leave it off and the call errors. A lookup by NPI looks like this:

GET https://npiregistry.cms.hhs.gov/api/?version=2.1&number=1234567890

A search by name and state looks like this:

GET https://npiregistry.cms.hhs.gov/api/?version=2.1&first_name=jane&last_name=carter&state=MI

The response is a JSON envelope with result_count and a results array, where each result carries the provider's enumeration_type (NPI-1 for individuals, NPI-2 for organizations), basic identity, NUCC taxonomies, and addresses. Wildcards are allowed on name fields with a trailing *, but the API will not let you run an empty, criteria-free query — you have to give it something to match on.

Where the free NPPES API stops

None of the following are bugs. They are design choices that make sense for a public reference tool and make less sense as the backbone of a product. Know them before you build.

Constraint What the NPPES API does Why it bites in production
Result cap per page limit maxes out at 200 records (api-page) Any broad query needs pagination logic
Pagination ceiling skip maxes out at 1000 (api-page) With limit 200, you can reach at most ~1,200 matching records for one query — you literally cannot page past it
Update cadence Registry updates daily Fine for reference; you own freshness handling either way
Scope NPPES demographic data only No Medicare (PECOS) enrollment status in the response
Required criteria Rejects empty/over-broad searches You must always supply enough to narrow the result set
Operations Read-only GET, JSON No batch endpoint, no webhooks, no push updates
Terms of service Public tool, no SLA, no support contract No uptime guarantee, no rate-limit contract, no one to call

The pagination ceiling is the one that surprises people. If you search a large state for a common specialty, you can retrieve the first ~1,200 matches and then the API simply stops handing you more, because skip will not go past 1000. There is no total-count endpoint either, so you discover the boundary by hitting it. For one-off lookups this never matters. For anything that enumerates providers, it is a wall.

Matching providers without generating garbage

The hardest part of provider data is not fetching a record — it is deciding that two records are the same provider. If your input is a clean ten-digit NPI, life is easy: look it up, done. Real inputs are rarely that clean. You get a name and a city, or a name and a specialty, from a form or a spreadsheet or a partner feed.

Two rules keep the false positives down:

  • Never match on a single field. "John Smith" is not a match. "John Smith, family medicine, 48099" is a candidate you can actually verify. Combine name with location and/or NUCC taxonomy before you trust a hit.
  • Treat multiple hits as a decision, not a default. When a name-and-state query returns three providers, do not silently take the first. Surface the candidates or apply a deterministic tiebreak; picking results[0] is how the wrong provider ends up in your database.

If you are hand-checking a handful of providers rather than wiring up code, our free NPI lookup tool resolves a single provider by NPI, name, or organization, and the advanced NPI search lets you filter by taxonomy, city, and state the same way the API does — a fast way to sanity-check your matching logic against a known-good result before you automate it.

When to move to a production API

The free NPPES API is the right tool for a low-volume, best-effort lookup where an occasional miss is acceptable. You should look past it when any of these become true:

  • You need an uptime and rate-limit contract, not a public endpoint that can throttle or change without notice.
  • You need Medicare (PECOS) enrollment status alongside the NPPES demographics — for example, to confirm a provider can bill before you onboard or refer.
  • You are enumerating providers and keep hitting the ~1,200-record pagination ceiling.
  • You want a predictable, stable response schema and real documentation you can build a contract test against.

That is the gap our own NPI Registry API is built for: the same provider lookups plus PECOS enrollment, clean JSON over REST, a weekly-refreshed dataset, and a free tier of 1,000 requests per month that provisions an API key by email — no credit card. It is a real-time verification service, not a data dump. If your need is the opposite — pulling large volumes of records offline for analytics rather than verifying one provider at a time — read our companion guide on the bulk NPI lookup API, which covers batch patterns and where a downloadable file beats an API call.

Integration checklist

Before you call your NPI integration done, walk this list:

  • Always send version=2.1. Missing version is the most common first-call failure.
  • Handle pagination. Loop on skip until a page returns fewer than limit records — and know you cannot page past skip 1000 on the free API.
  • Match on more than one field. Name plus location or taxonomy, never name alone.
  • Resolve multiple hits deliberately. No blind results[0].
  • Distinguish NPI-1 from NPI-2. Individual and organization records have different name fields.
  • Cache with a refresh policy. The source updates daily; decide how stale is too stale for your use case.
  • Fail gracefully. A public endpoint with no SLA will occasionally time out; do not let a provider lookup take down your onboarding flow.

Frequently asked questions

Is the NPI Registry API free? Yes. CMS runs the NPPES NPI Registry API as a free, query-only service with no charge to view the data and no account required (CMS Data Dissemination). Commercial APIs like ours add scope, a support contract, and enrollment data on top of that public foundation.

Do I need an API key for the NPPES API? No. The free CMS endpoint takes anonymous GET requests. A key only comes into play with a commercial provider API — for example, ours emails you one when you start on the free tier.

How current is the data? The NPPES NPI Registry is updated daily by CMS (CMS Data Dissemination). Note that a commercial API may refresh on its own cadence; ours refreshes weekly.

Why does my search return only 200 results? That is the per-page limit maximum on the NPPES API. Paginate with the skip parameter, but remember skip caps at 1000, so a single query can surface at most about 1,200 records (NPPES NPI Registry API).

Can the API tell me if a provider is enrolled in Medicare? Not the free NPPES API — it returns NPPES demographic data only. To verify Medicare (PECOS) enrollment status by NPI, PAC ID, or enrollment ID, you need a service that joins that data in, such as our NPI Registry API.

This article is educational and not legal advice. Provider Signals is not a consumer reporting agency and this is not FCRA-regulated data; nothing here is legal advice. NPI Data Services is not affiliated with or endorsed by any government agency.

Ready to build against provider data that comes with PECOS enrollment, a stable schema, and support? Get a free API key — 1,000 requests a month, no credit card, key emailed in seconds.

Related posts

Data & analytics

Bulk NPI Lookup: Enrich Your Database via API

Two ways to run a bulk NPI lookup — the free NPPES download and a record-by-record API — and how to pick the right one to enrich a provider database.

Aug 20, 2026 · 9 min read
Data & analytics

5 Ways Health-Tech Teams Use a Provider Data API

Five concrete ways EMR, digital-health, and RCM teams put a provider data API to work — from onboarding to directory freshness to referral analytics.

Oct 26, 2026 · 9 min read