API for NPI (National Provider Identifier) Records - Individuals

This API uses the NPI (National Provider Identifier) data from CMS (Centers for Medicare & Medicaid Services), the Health Care Provider Taxonomy from NUCC (National Uniform Claim Committee), and the Crosswalk Medicare Provider/Supplier to Healthcare Provider Taxonomy from CMS.

See the Data Construction section for more details.

API Demo

The following demo shows how this API might be used with an autocompleter we've developed.

For further experimentation with the autocompleter and this API, try the autocompleter demo page.

API Documentation

API Base URL: https://clinicaltables.nlm.nih.gov/api/npi_idv/v3/search (+ query string parameters)

This data set may also be accessed through the FHIR ValueSet $expand operation.

In addition to the base URL, you will need to specify other parameters. See the query string parameters section below for details.

Query String Parameters and Default Values

At a minimum, when using the above base URL, you will need to specify the "terms" parameter containing a word or partial word to match.

Parameter NameDefault ValueDescription
terms(Required.) The search string (e.g., just a part of a word) for which to find matches in the list. More than one partial word can be present in "terms", in which case there is an implicit AND between them.
maxList Optional, with a default of 7. Specifies the number of results requested, up to the upper limit of 500. If present but the value is empty, 500 will be used.
qAn optional, additional query string used to further constrain the results returned by the "terms" field. Unlike the terms field, "q" is not automatically wildcarded, but can include wildcards and can specify field names. See the Elasticsearch query string page for documentation of supported syntax.
df NPI, name.full, provider_type, addr_practice.full A comma-separated list of display fields (from the fields section below) which are intended for the user to see when looking at the results.
sfNPI, name.full, provider_type, addr_practice.fullA comma-separated list of fields (or path to record json object) to be searched.
cfNPIThe NPI ID, it's the unique record ID.
efA comma-separated list of additional fields to be returned for each retrieved list item. (See the Output format section for how the data for fields is returned.) If you wish the keys in the returned data hash to be something other than the field names, you can specify an alias for the field name by separating it from its field name with a colon, e.g., "ef=field_name1:alias1,field2,field_name3:alias3,etc. Note that not every field specified in the ef parameter needs to have an alias.

NPI Field Descriptions

Important notes on the data fields
FieldField Description
NPINational Provider Identifier of the provider.
provider_typeThe provider (specialty) type. The provider type is determined based on the provider's primary (or first, if primary not indicated) taxonomy code. If the taxonomy code has a corresponding medicare provider type, that type will be used; if not, the taxonomy classification will be used. For other types/specialties of a provider, see the 'licenses' field below for details.
genderGender of the provider.
name.fullThe full name string of the provider.
addr_practice.fullThe full address string of the practice address.
licensesA list of license objects for the provider, each with sub-fields such as issuing states, taxonomy, corresponding medicare provider type, etc. For search, use its specific sub-fields.
licenses.taxonomyThe taxonomy object (with sub-fields) for the provider's corresponding license. For search, use its specific sub-fields.
licenses.taxonomy.codeThe taxonomy code for the provider's corresponding license.
licenses.taxonomy.groupingThe taxonomy 'grouping' for the provider's corresponding license.
licenses.taxonomy.classificationThe taxonomy 'classification' for the provider's corresponding license.
licenses.taxonomy.specializationThe taxonomy 'specialization' for the provider's corresponding license.
licenses.medicareThe medicare type object (with sub-fields) for the provider's corresponding license. For search, use its specific sub-fields.
licenses.medicare.spc_codeThe medicare type specialty code for the provider's corresponding license.
licenses.medicare.typeThe medicare provider type for the provider's corresponding license.
nameThe name object (with sub-fields) of the provider. For search, use name.full or other specific sub-fields.
name.lastThe last name of the provider.
name.firstThe first name of the provider.
name.middleThe middle name of the provider.
name.credentialThe credential (e.g., MD, RN) of the provider.
name.prefixThe prefix of the provider name.
name.suffixThe suffix of the provider name.
addr_practiceThe provider's practice address object (with sub-fields). For search, use addr_practice.full or other specific sub-fields.
addr_practice.line1The line1 (street address) of the provider's practice address.
addr_practice.line2The line2 (e.g., suite#) of the provider's practice address.
addr_practice.cityThe city of the provider's practice address.
addr_practice.stateThe state of the provider's practice address.
addr_practice.zipThe zip code of the provider's practice address.
addr_practice.phoneThe phone number for the provider's practice address.
addr_practice.faxThe fax number for the provider's practice address.
addr_practice.countryThe country for the provider's practice address.
addr_mailingThe provider's mailing address object (with sub-fields). For search, use addr_mailing.full or other specific sub-fields.
addr_mailing.fullThe full address string of the mailing address.
addr_mailing.line1The line1 (street address) of the provider's mailing address.
addr_mailing.line2The line2 (e.g., suite#) of the provider's mailing address.
addr_mailing.cityThe city of the provider's mailing address.
addr_mailing.stateThe state of the provider's mailing address.
addr_mailing.zipThe zip code of the provider's mailing address.
addr_mailing.phoneThe phone number for the provider's mailing address.
addr_mailing.faxThe fax number for the provider's mailing address.
addr_mailing.countryThe country for the provider's mailing address.
name_otherThe provider's 'other name' object (with sub-fields). For search, use name_other.full or other specific sub-fields.
name_other.fullThe full name string for the 'other name' of the provider.
name_other.lastThe last name of the provider's other name.
name_other.firstThe first name of the provider's other name.
name_other.middleThe middle name of the provider's other name.
name_other.credentialThe credential (e.g., MD, RN) of the provider's other name.
name_other.prefixThe prefix of the provider's other name.
name_other.suffixThe suffix of the provider's other name.
other_idsA list of other ids issued by various agencies/organizations, each with sub-fields. For search, use specific sub-fields.
other_ids.idThe id of the 'other id'.
other_ids.typeThe type of the other id.
other_ids.issuerThe issuer of the other id.
other_ids.stateThe state of the other id.
miscAn object with sub-fields for the other, misc data elements.
misc.auth_officialThe 'authorized official' object for the provider, with sub-fields. For search, use specific sub-fields.
misc.auth_official.lastThe last name of the provider's authorized official.
misc.auth_official.firstThe first name of the provider's authorized official.
misc.auth_official.middleThe middle name of the provider's authorized official.
misc.auth_official.credentialThe credential (e.g., MD, RN) of the provider's authorized official.
misc.auth_official.titleThe title of the provider's authorized official.
misc.auth_official.prefixThe prefix of the provider's authorized official name.
misc.auth_official.suffixThe suffix of the provider's authorized official name.
misc.auth_official.phoneThe phone of the provider's authorized official.
misc.replacement_NPIThe provider's replacement NPI number.
misc.EINThe provider's EIN, rarely populated.
misc.enumeration_dateThe enumeration data of the provider.
misc.last_update_dateThe provider entry's last update date.
misc.is_sole_proprietorThe provider sole proprietor flag.
misc.is_org_subpartThe provider organization subpart flag.
misc.parent_LBNThe provider organization subpart legal business name.
misc.parent_TINThe provider organization subpart TIN.

Output format

Output for an API query is an array of the following elements:

  1. The total number of results on the server (which can be more than the number returned). For APIs in which there are millions of records, this number might be a lower bound due to early termination if there are more than a hundred thousand results.
  2. An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
  3. A hash of the "extra" data requested via the "ef" query parameter above. The keys on the hash are the fields (or their requested aliases) named in the "ef" parameter, and the value for a field is an array of that field's values in the same order as the returned codes.
  4. An array, with one element for each returned code, where each element is an array of the display strings specified with the "df" query parameter.
  5. An array, with one element for each returned code, where each element is the "code system" for the returned code. Note that only code-system aware APIs will return this array.

Sample API Queries

QueryResultDescription
https://clinicaltables.nlm.nih.gov/api/npi_idv/v3/search?terms=john+bethesda [127,["1760880173","1033132295","1043763485","1427180405","1447647847","1710044342","1760833891"],null,[["1760880173","JOHN KELLY","Dentist","4833 BETHESDA AVE STE 302, BETHESDA, MD 20814, US"],["1033132295","JOHN STURGEON","Physician/Diagnostic Radiology","6204 DUNROBBIN DR, BETHESDA, MD 20816, US"],["1043763485","CAROLYN JOHNSON","Occupational Therapist in Private Practice","9241 VENDOME DR, BETHESDA, MD 20817, US"],["1427180405","JOHN GERSHEFSKI","Psychologist, Clinical","6809 WHITTIER BLVD, BETHESDA, MD 20817, US"],["1447647847","JOHN DELANEY","Student in an Organized Health Care Education/Training Program","8901 WISCONSIN AVE, BETHESDA, MD 20889, US"],["1710044342","JOHN ZINNER","Physician/Psychiatry","7111 LAVEROCK LN, BETHESDA, MD 20817, US"],["1760833891","JOHN ORISASONA","Home Health Aide","3812 BETHESDA CT, CHESTER, VA 23831, US"]]] Returns 7 (out of 126 total) providers whose records match "john" and "bethesda".
https://clinicaltables.nlm.nih.gov/api/npi_idv/v3/search?terms=williams&ef=other_ids [26306,["1225588858","1023354495","1750728010","1427045632","1720065618","1639149511","1215932470"],{"other_ids":[[{"state":"PA","type":"05","id":"282NW0100X"},{"state":"OR","type":"05","id":"213ES0000X"},{"state":"OR","type":"05","id":"3416AD800X"},{"state":"OR","type":"05","id":"347C00000X"},{"state":"OR","type":"05","id":"302F00000X"},{"state":"OR","type":"05","id":"25300000X"},{"state":"OR","type":"05","id":"305R00000X"},{"state":"OR","type":"05","id":"251T0000X"},{"state":"OR","type":"05","id":"305500000X"}],null,null,[{"type":"02","id":"G91672"},{"state":"MA","type":"05","id":"110061100/A"},{"state":"MA","type":"08","id":"A2949902"}],[{"state":"VA","type":"01","id":"42727","issuer":"VETRI"},{"state":"VA","type":"01","id":"12953700002","issuer":"SOUTHERN HEALTH"},{"state":"VA","type":"01","id":"010723","issuer":"CIGNA"},{"state":"VA","type":"01","id":"267257","issuer":"MAMSI/ALLIANCE"},{"state":"VA","type":"01","id":"333844","issuer":"ANTHEM"}],[{"type":"02","id":"E28498"}],[{"state":"PA","type":"02","id":"R682337"}]]},[["1225588858","RYAN MATTHEW ANLIKER I","Specialist","18151 WILLIAMS HWY, WILLIAMS, OR 97544, US"],["1023354495","MARY WILLIAMS WILLIAMS","Social Worker","1 FREEDOM WAY, AUGUSTA, GA 30904, US"],["1750728010","CODY WILLIAMS WILLIAMS","Student in an Organized Health Care Education/Training Program","1514 JEFFERSON HWY BRENT HOUSE ROOM 634, NEW ORLEANS, LA 70121, US"],["1427045632","GREGORY WILLIAMS","Physician/Family Practice","382 DW HWY, MERRIMACK, NH 03054, US"],["1720065618","ELIZABETH WILLIAMS","Physician/Pediatric Medicine","1011 E JEFFERSON ST, CHARLOTTESVILLE, VA 22902, US"],["1639149511","TIMOTHY WILLIAMS","Physician/Addiction Medicine","2900 CHANTICLEER AVE, SANTA CRUZ, CA 95065, US"],["1215932470","CINDY WILLIAMS","Registered Nurse","899 POPLAR CHURCH RD, CAMP HILL, PA 17011, US"]]] Returns 7 (out of 26,306 total) providers whose records match "williams". Note that the parameter "ef=other_ids" tells the service to return other ids issued to the provider by various organizations

Data Construction

This section briefly describes how a data record is constructed in this API.

First of all, a record is constructed based on the data elements from the following sources:

The data construction starts from an NPI record:

  1. Filter out records that have been deactivated.
  2. Minor formatting on phone numbers, zip codes, credential texts, etc.
  3. For individuals (as opposed to organizations) only, construct full name strings from the name "parts" (e.g., first name, last name) in the NPI record.
  4. Construct full address strings from address "parts" (e.g., line1, line2, city) in the NPI record.
  5. For each license of the provider, take the taxonomy code and look up in the taxonomy, if a taxonomy entry is found, it will be included in the record.
  6. For each license of the provider, take the taxonomy code and look up in the crosswalk, if an entry is found, the Medicare provider type and specialty code will be included in the record.
  7. Add the top-level "provider type". Usually one of the provider's licenses is marked as "primary taxonomy", if not, the first license in the list will be used as "primary". This primary entry, if exists, is then used to decide the provider type: if there is a Medicare provider type for the entry, that type will be used; if not, the taxonomy's "classification" value will be used.