NPI JSON API — GET /api/v3/npi

Overview

NPIPublicData.org provides a read-only JSON API so you can integrate NPI data lookups into your apps and workflows. We’re not affiliated with CMS or HHS. This page covers authentication, the endpoint URL, query parameters, response shape, and fair use. For accuracy, ads, and liability, read the Disclaimer. For official record verification, use the NPPES NPI Registry.

Migration: If you previously called /api/v3/npi without a key, add Authorization: Bearer or X-Api-Key as described below. Need access? Contact us or email [email protected].

Authentication

Every request to GET /api/v3/npi must include a valid API key. Send the key in either header below (you do not need both). If both are present, X-Api-Key is used.

Authorization: Bearer YOUR_API_KEY
X-Api-Key: YOUR_API_KEY

Do not pass keys in the query string (e.g. ?api_key=). Requests that include api_key as a query parameter receive 400.

Missing or invalid keys receive 401 with {"error":true,"message":"...","docs":"/api/"}. When you exceed per-key or per-IP rate limits, you receive 429 with a Retry-After header (seconds). If the rate-limit store is unavailable (e.g. disk permissions), you may receive 503 with Retry-After: 30. Successful responses include X-RateLimit-Remaining, X-RateLimit-Limit (per key), and when IP limiting applies, X-RateLimit-Limit-Ip.

Quick start

Obtain an API key from us (see Authentication). Keys are not passed in the URL.
Copy the /api/v3/npi base URL (GET only).
Add query params (at least one search field, e.g. number=1467550004).
Send Authorization: Bearer or X-Api-Key on every request. Expect 200 JSON with results, or 400/401/429/503/502 with our error object when applicable.
Need pretty-printed JSON for debugging? Pass pretty=True when supported.

Ways to use our data

Pick what fits. Use the NPI Lookup for quick browser searches (no code). Use this JSON API when you’re building an app or script and want structured responses. When you need full-file extracts for analytics or a warehouse, use Downloads: batch files aren’t the same as the live API.

We send permissive CORS headers on the JSON endpoint so browsers can complete cross-origin GET requests with Authorization / X-Api-Key after preflight. Do not embed API keys in public client-side code. Call the API from your server (or a non-public app) so the key stays secret.

JSON API

GET /api/v3/npi is our current API for live NPI JSON (v3 is the version you integrate against in the URL). Read-only; API key required on every call. If you omit limit, we default it; you do not need any extra “format version” query parameter for normal use.

GET /api/v3/npi

API base URL https://npipublicdata.org/api/v3/npi

Append the query parameters below to your request.

Try in the browser? Opening /api/v3/npi?... in a new tab will not send your API key. Use curl, Postman, or code with headers. Copy the examples below.

Methods: GET for data; OPTIONS for CORS preflight (allowed headers include Authorization and X-Api-Key).
Defaults we apply: limit=20 if you omit it; any low-level compatibility fields required by the search layer are set automatically when omitted.
limit range: 1 to 200 per request.
Our errors: 400 (bad request or disallowed api_key query), 401 (missing/invalid key), 405, 429 (rate limit), 503 (rate limiter store unavailable), or 502 with {"error":true,"message":"..."} when we can’t complete the request. Search validation may still return 200 with an Errors array in the body. Read those objects and adjust your query params.

API path & paging

Why `/api/v3/npi`?

The v3 segment is the API version: use this path for all new integrations. When we ship a new major revision, it will appear as a new path (e.g. /api/v4/npi) and we’ll document migration here.

Optional query key version: You may see this name in copied URLs or older examples. You can omit it. Our service applies the correct value automatically. It is not a second “API version” alongside v3; treat v3 in the path as the version you target.

Paging

Per request: up to 200 rows (limit), and skip from 0 to 1000. With paging you can retrieve on the order of 1,200 rows across multiple calls (e.g. six requests at limit=200). See limit and skip in the parameter table.

Note: Having an NPI doesn’t prove licensure or credentials. Check state boards and payers when that matters.

Query parameters

Send at least one real search field, plus optional limit, skip, or pretty. Don’t send enumeration_type alone; pair it with another criterion.

Wildcards, special characters in names, and which fields can be used alone follow the rules summarized in this table. For edge cases, see Help & reference.

Parameter	Summary
`version`	Optional. Omit for normal integrations; we set it server-side. Only include if you are reproducing a legacy query string; unsupported values may fail.
`number`	10-digit NPI.
`enumeration_type`	`NPI-1` (individual) or `NPI-2` (organization); not alone.
`taxonomy_description`	Taxonomy / specialty text.
`name_purpose`	`AO` (authorized official) or `PROVIDER` (provider name); controls which name fields apply.
`first_name`	Individual / AO first name; trailing wildcards allowed (min two characters before `*`).
`use_first_name_alias`	`True` or `False` (also `1`/`0`); alias matching for first names. Default: True.
`last_name`	Individual last name; wildcards and minimum character rules apply (see notes below).
`organization_name`	Organization name (Type 2); wildcards supported.
`address_purpose`	`LOCATION`, `MAILING`, `PRIMARY`, or `SECONDARY` (which address rows the location filters apply to).
`city`	City (e.g. `APO` / `FPO` for military mail).
`state`	Two-letter state; usually cannot be the only search criterion. Combine with other fields as needed.
`postal_code`	ZIP; 5-digit matches ZIP+4; wildcards allowed.
`country_code`	Country; when `US`, pair with additional criteria unless documented otherwise.
`limit`	1 to 200; we default to 20 if omitted.
`skip`	0 to 1000 (rows to skip before returning matches).
`pretty`	`True` / `False` (or `1` / `0`). Requests human-readable JSON when supported.

Advanced searches often can’t be state-only; add city, postal code, or taxonomy for more context.

Example requests

Example request URLs

Replace YOUR_API_KEY with your key. These examples use the v3 path.

By NPI (URL only; you still need the header in real requests)

https://npipublicdata.org/api/v3/npi?number=1467550004

cURL by NPI (with key)

curl -s -H "X-Api-Key: YOUR_API_KEY" "https://npipublicdata.org/api/v3/npi?number=1467550004"

cURL Bearer alternative

curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://npipublicdata.org/api/v3/npi?first_name=John&last_name=Smith&state=CA&limit=10"

By name & state (URL only)

https://npipublicdata.org/api/v3/npi?first_name=John&last_name=Smith&state=CA&limit=10

cURL (same as quick reference)

curl -s -H "X-Api-Key: YOUR_API_KEY" "https://npipublicdata.org/api/v3/npi?number=1467550004"

Responses

Successful responses usually include result_count and a results array of provider objects. Field names and structure match the v3 JSON API as documented on this page.

Expect an addresses array (first item: primary practice location, second: mailing), plus arrays for taxonomies, other names, endpoints, practice locations, and other identifiers. If you align JSON with columns from our bulk exports (see Downloads), use Help & reference for mapping questions.

Bad queries sometimes still return 200 with an Errors array (description, optional field). Parse those before you assume success.

Help & reference

For how the site works, FAQs, and general NPI lookup help, see the Knowledge Base and FAQs. For detailed integration questions, parameter edge cases, or bulk-vs-API field mapping, contact us or email [email protected]. We’re happy to point you to the right resources.

CORS and fair use

We send Access-Control-Allow-Origin: * on /api/v3/npi so browser apps on other domains can read responses for legitimate lookups.

Cache responses when you can, back off on errors, and don’t use the live API to scrape the whole directory. For full files, use Downloads. We enforce per-key and per-IP rate limits (see Authentication); heavy or abusive traffic may be blocked.

Bulk NPI data

The JSON API is for interactive queries. For scheduled full-file and incremental releases, see Downloads (how exports differ from API rows).

NPIPublicData.org provides live NPI data from NPPES (the National Plan and Provider Enumeration System). We do not modify, rewrite, or edit provider records: successful responses reflect the registry’s live data for your query, returned as NPPES supplies it. Our gateway may apply documented defaults (for example optional query parameters), authentication, rate limits, and error handling only.

Please note: Issuance of an NPI does not ensure or validate that the health care provider is licensed or credentialed. For more information, see CMS’s Educational Resources. Check state boards, payers, and other primary sources when licensure or credentials matter.

API Documentation