The CMS NPI Registry API, version 2.1 (https://npiregistry.cms.hhs.gov/api/?version=2.1, no key): one provider by NPI, and searches by name, organization, taxonomy and location.

Search limits. A request returns up to 200 records (default 10) and can skip up to 1,000, so one set of criteria reaches 1,200 records over six requests. The API doesn't report a total, and it answers a limit or skip above the maximum as if it were the maximum, without saying so: past 1,000, skip returns the same records again. So search caps limit and refuses a higher skip.

next-page gives the next skip, and collect follows it to the end of that reach.

Every function takes an optional trailing opts Map: the criteria listed at search-params, limit, skip, and base-url.

Context Vars

Optional
  • nppes.base-url

Values

DEFAULT_LIMIT

DEFAULT_LIMIT: Int 10

MAX_LIMIT

MAX_LIMIT: Int 200

MAX_SKIP

MAX_SKIP: Int 1000

PARAMS

PARAMS: Map {
  number: "number",
  enumeration-type: "enumeration_type",
  taxonomy-description: "taxonomy_description",
  name-purpose: "name_purpose",
  first-name: "first_name",
  last-name: "last_name",
  organization-name: "organization_name",
  address-purpose: "address_purpose",
  city: "city",
  state: "state",
  postal-code: "postal_code",
  country-code: "country_code"
}

VERSION

VERSION: Str "2.1"

Functions

address-for

fn (provider: Any, purpose: Str): Map?

alias-param

fn (value: Any): Str?

collect

fn (fetch: Fn, opts: Map, limit: Int): Vec

Follow pages until limit records or the API's reach. fetch takes opts (with limit and skip set) and returns one page. An Err on any page is returned in place of the records. One search reaches skip 1,000 plus a page, so 1,200 records at the default 200 a page. Exactly that many means there may be more: narrow the criteria, by state or postal code, and collect again.

Example

rows ::nppes/collect((o) { ::nppes/organizations("mayo clinic*", o) }, {state: "MN"}, 500)

collect-pages

fn (fetch: Fn, opts: Map, start: Int, limit: Int, acc: Vec): Vec

final-skip

fn (page: Any, opts: Map): Int?

get-provider

fn (npi: Any): Map?
fn (npi: Any, opts: Map): Map?

One provider by NPI, or null when the registry has none. An NPI that isn't 10 digits is an Err from the API; is-npi checks one first.

Example

provider ::nppes/get-provider("1881018208")
provider.basic.organization_name       // "MAYO CLINIC"
::nppes/primary-taxonomy(provider).desc

individuals

fn (last-name: Str): Map
fn (last-name: Str, opts: Map): Map

Search individual providers (Type 1 NPIs) by last name, with first-name and any other criteria in opts.

is-active

fn (provider: Any): Bool

True when the record's basic.status is "A" (pure).

is-npi

fn (npi: Any): Bool

True for a syntactically valid NPI: 10 digits with a valid Luhn check digit, computed with the 80840 health-industry prefix (pure). It says nothing about whether the NPI was issued.

location-address

fn (provider: Any): Map?

A provider's primary practice location address, or null (pure). Other locations are in practiceLocations.

luhn-sum

fn (digits: Str): Int

mailing-address

fn (provider: Any): Map?

A provider's mailing address, or null (pure).

next-page

fn (page: Any, opts: Map): Int?

The skip after page, or null when the page came back short or the next skip would pass 1,000 (pure). opts are the ones that fetched page. The API gives no total, so a full last page gets one more, empty, request.

organizations

fn (name: Str): Map
fn (name: Str, opts: Map): Map

Search organizational providers (Type 2 NPIs) by name, with any other criteria in opts.

page-limit

fn (opts: Map): Int

opts.limit, capped at 200, or 10 when unset (pure).

primary-taxonomy

fn (provider: Any): Map?

The taxonomy marked primary, {code, desc, license, state, primary, taxonomy_group}, or null (pure).

registry-get

fn (opts: Map): Any

results

fn (page: Any): Vec<Map>

The provider records in a page (pure).

fn (opts: Map): Map

Search the registry. Returns the API's page: result_count (the records in this page, not the total) and results. Read it with results. Criteria the API rejects are an Err, such as state alone or a wildcard after one letter. An Err too when skip is over 1,000, which the API would answer with repeated records.

Example

page ::nppes/search({organization-name: "mayo clinic*", state: "MN", limit: 50})
first(::nppes/results(page)).basic.organization_name

search-params

fn (opts: Map): Map

Query parameters for a search (pure). first-name, last-name, organization-name, taxonomy-description, city and postal-code take a trailing * after at least two characters.

opts keyMeaning
numberA 10-digit NPI
enumeration-type"NPI-1" (individuals) or "NPI-2" (organizations); needs other criteria
first-name, last-nameIndividuals, or authorized officials with name-purpose: "AO"
use-first-name-aliastrue (the API's default) also matches similar first names; false is exact
name-purpose"AO" or "PROVIDER"
organization-nameOrganizations; checks every name on the record, including former and other names
taxonomy-descriptionAn exact taxonomy description or specialty
address-purpose"LOCATION", "MAILING", "PRIMARY" or "SECONDARY"
city, postal-codeA 5-digit code also matches ZIP+4
stateTwo letters; needs another criterion besides enumeration-type and country-code
country-codeTwo letters; "US" needs other criteria
limit, skipPage size up to 200; records to skip, up to 1,000