NPPES Getting Started: API Access and First Request (2026)

Getting started overview

The National Plan and Provider Enumeration System (NPPES) NPI Registry provides a public API to access National Provider Identifier (NPI) data. Unlike many commercial APIs, the NPPES NPI Lookup API does not require an account, API keys, or any form of authentication for basic searches. This design enables developers to integrate directly without an initial setup phase for credentials. The API supports queries based on various parameters such as NPI, provider name, or address, returning results in JSON format. The primary documentation for the NPI Registry API is available on the NPI Registry API page. Developers can also find comprehensive information regarding the NPI program and registry on the CMS NPI program homepage.

This guide outlines the process for making your first request to the NPPES NPI Registry API. The steps include identifying the API endpoint, constructing a query, and interpreting the JSON response. Given the absence of authentication, the focus is on correct URL construction and parameter usage.

Here's a quick reference for getting started:

Create an account and get keys

The NPPES NPI Lookup API is publicly accessible and does not require developers to create an account or obtain API keys for making requests. This simplifies the onboarding process significantly, as there are no authentication mechanisms to manage. Developers can proceed directly to constructing API calls once they understand the available parameters and expected response formats. The public nature of the API aligns with its goal of providing readily available NPI data for healthcare-related applications. For more detailed information, consult the official NPI Registry API documentation.

While direct API access is open, users seeking to update or manage NPI records must utilize the NPPES website login, which is a separate process for data submission and is not related to consuming the public NPI Lookup API.

Your first request

To make your first request to the NPPES NPI Lookup API, you will need to construct a URL with the appropriate query parameters. The base URL for the API is https://npiregistry.cms.hhs.gov/api/. You can append parameters to this URL to filter your search. The API supports various search criteria, including NPI number, provider name, organization name, and address information. A common way to test the API is by searching for an NPI directly or by a provider's name.

Example: Search by NPI

To search for a specific NPI (e.g., 1234567890), you would use the number parameter:

curl "https://npiregistry.cms.hhs.gov/api/?number=1234567890"

Replace 1234567890 with a valid NPI to get actual results. For instance, using the example NPI 1922002773:

curl "https://npiregistry.cms.hhs.gov/api/?number=1922002773"

The JSON response for a successful query will contain an array of results, each representing a provider matching the criteria. The structure includes fields like NPI, enumeration_date, basic information (e.g., first name, last name), and addresses.

Example: Search by Provider Name

You can also search by a provider's first and last name. For example, to search for "John Doe":

curl "https://npiregistry.cms.hhs.gov/api/?first_name=John&last_name=Doe"

This query will return all providers matching the specified first and last names. The API allows for partial matches, which can be useful but may also return a large number of results.

Key Parameters for Searching

• number: The 10-digit NPI.
• first_name: Provider's first name.
• last_name: Provider's last name.
• organization_name: Name of the organization.
• city: Provider's practice location city.
• state: Provider's practice location state (two-letter abbreviation).
• postal_code: Provider's practice location postal code.
• limit: Maximum number of results to return (default is 10, maximum is 200).
• skip: Number of results to skip for pagination.

A full list of searchable parameters and their descriptions can be found in the NPI Registry API documentation.

Common next steps

After successfully making your first request to the NPPES NPI Registry API, common next steps involve integrating the API into your application and implementing robust error handling and data processing. Given the public nature and lack of authentication, scaling involves careful consideration of rate limits and data management.

Integrate with a Programming Language

Most applications will consume the API using a programming language. Here's a Python example using the requests library:

import requests
import json

def search_npi(npi_number):
    base_url = "https://npiregistry.cms.hhs.gov/api/"
    params = {"number": npi_number}
    try:
        response = requests.get(base_url, params=params)
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        data = response.json()
        if data.get('result_count', 0) > 0:
            for provider in data['results']:
                print(f"NPI: {provider['number']}")
                print(f"Name: {provider['basic']['first_name']} {provider['basic']['last_name']}")
                for address in provider['addresses']:
                    if address['address_purpose'] == 'LOCATION':
                        print(f"Location: {address['address_1']}, {address['city']}, {address['state']} {address['postal_code']}")
        else:
            print(f"No results found for NPI: {npi_number}")
    except requests.exceptions.HTTPError as errh:
        print(f"Http Error: {errh}")
    except requests.exceptions.ConnectionError as errc:
        print(f"Error Connecting: {errc}")
    except requests.exceptions.Timeout as errt:
        print(f"Timeout Error: {errt}")
    except requests.exceptions.RequestException as err:
        print(f"Something Else: {err}")

# Example usage:
search_npi("1922002773")
search_npi("9999999999") # Example of an NPI that might not exist

This Python code snippet demonstrates how to send a GET request, handle potential HTTP errors, and parse the JSON response. The requests library simplifies HTTP interactions, as detailed in its official documentation.

Error Handling and Edge Cases

Implement robust error handling for various scenarios, such as:

• No results found: The API returns "result_count": 0 if no providers match the query. Your application should handle this gracefully.
• Invalid parameters: While the API attempts to be lenient, malformed URLs or unexpected parameter values might lead to errors.
• Network issues: Implement retries and timeouts for network connectivity problems.

Pagination

For queries that return a large number of results, utilize the limit and skip parameters to paginate through the data. The maximum limit is 200 results per request. For example, to get the next 200 results after the first:

curl "https://npiregistry.cms.hhs.gov/api/?first_name=John&last_name=Doe&limit=200&skip=200"

Data Storage and Caching

Consider caching NPI data that is frequently accessed to reduce the number of API calls and improve application performance. Ensure your caching strategy complies with any relevant data retention policies or regulations, although the NPPES API itself does not specify caching restrictions.

Rate Limits and Fair Use

While explicit rate limits are not documented, the API is a public resource. Developers are expected to use it responsibly and avoid excessive querying that could impact service availability for others. Distributing requests over time and caching data can help adhere to a fair use policy.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to troubleshooting typical problems with the NPPES NPI Lookup API:

1. Check the URL for typos: Ensure the base URL https://npiregistry.cms.hhs.gov/api/ is correct and that all parameter names (e.g., number, first_name) are spelled accurately and in lowercase. Incorrect casing or spelling will prevent the API from recognizing the parameters.

2. Verify parameter values:

   • NPI: Must be a 10-digit number.
   • State: Should be a two-letter abbreviation (e.g., NY for New York).
   • Postal Code: Can be a 5-digit or 9-digit (ZIP+4) code.
   • Names: Ensure names are URL-encoded if they contain special characters or spaces (though curl typically handles this for simple spaces).

3. Examine the response:

   • Empty results array: If "result_count": 0 is returned, it means no providers matched your specific query. Try broadening your search criteria or double-checking the accuracy of the NPI or name you are searching for.
   • HTTP status codes: While the NPPES API generally returns 200 OK even for no results, other status codes could indicate issues:
   • 4xx (Client Error) codes, though rare for this public API, could suggest a malformed request if you're using a specific client library.
   • 5xx (Server Error) codes would indicate a problem on the API server's side. If you encounter these, wait and retry.

4. Use a browser to test: You can paste your constructed API URL directly into a web browser. The browser will display the JSON response, which can help you quickly verify if your URL is valid and returning data, before integrating it into code.

5. Review API documentation: The NPI Registry API documentation is the authoritative source for valid parameters and expected responses. Cross-reference your query with the examples provided there.

6. Check network connectivity: Ensure your environment has unobstructed internet access to npiregistry.cms.hhs.gov. Firewall rules or proxy settings could block external API calls. Tools like ping or traceroute (or tracert on Windows) can help diagnose network reachability issues to the hostname.

7. Consider URL encoding: If your query parameters contain spaces or special characters, ensure they are properly URL-encoded. While most HTTP client libraries handle this automatically, direct curl commands or manual URL construction might require it. For example, a space should be %20. The MDN Web Docs on URL encoding provides more details.

By systematically checking these points, you should be able to identify and resolve most issues encountered when making your first call to the NPPES NPI Lookup API.