NPPES Read API Documentation

NPPES Read API (DRAFT Updated November 9, 2016)

The NPI Read APIs facilitates machine readable documents about public health care provider information in the United States.

The URls described here are early prototypes designed to allow developers a chance to build, test and provide feedback prior to an actual go-live planned for May 2015.

This document outlines how to get data from the NPPES read API. Ad the name suggests these resources are read-only for the public and rely on the HTTP GET method.

No authentication is necessary at this time. There are two main parts of the Read API; 1.) the static provider resource, currently hosted at http://providers.npi.io and 2.)the searchable API currently hosted at https://registry.npi.io. It is reccomended that you rely on the provider static resource as much as possible and reserve the searchable API for when an actual search is needed. The public data dissemination will also be avaiable in its current CSV form.

The Provider Static Resource

The provider static resource is indexed by the NPI number itself. The results are returned in provider JSON format as described here https://github.com/HHSIDEAlab/pjson. This service also supports Cross Origin Resource Sharing (CORS).

Use HTTP GET to get the data from the server

An example in curl may look like:

curl -X GET http://npi.npi.io/npi/[NPI].json
		

where [NPI] is replaced by an actual NPI number. For example:

curl -X GET http://npi.npi.io/npi/1205824083.json
		

The Searchable Provider API

This API accepts GET parameters as search criteria. To search within a sub-field of the Provider JSON object use dot notation, Note that not all fields are indexed so the server may time out in these cases. Common fields such as name, state, enumeration type, (NPI) number, and city, are indexed. Results are limited to 200 per query. Results are always returned in a JSON object that looks like this:


{
type: "search-results",
code: 200,
results: []
}

The results is an array containing the provider JSON objects matching the query.

The following are examples in curl.

Fetch the first 200 results in the database:

curl -X GET https://registry.npi.io/search/api/public/nppes/pjson/pjson.json

Fetch the next 200 results:

curl -X GET 'https://registry.npi.io/search/api/public/nppes/pjson/pjson.json?skip=200'

Get a single NPI: This is only an example. Please use the Provider Static Resource for this purpose.

curl -X GET 'https://registry.npi.io/search/api/public/nppes/pjson/pjson.json?number=1205824083'

Get all providers with the last name Smith

curl -X GET 'https://registry.npi.io/search/api/public/nppes/pjson/pjson.json?basic.last_name=SMITH'

Get all providers with the last name Smith in Rhode Island

curl -X GET 'https://registry.npi.io/search/api/public/nppes/pjson/pjson.json?basic.last_name=SMITH&addresses.state=RI'