API for NPI (National Provider Identifier) Records - Organizations
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.
This service is provided "as is" and free of charge. Please see the Frequently Asked Questions page for more details on terms of service, etc.
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_org/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 Name | Default Value | Description |
|---|---|---|
| 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 | 7 | 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. Note that this parameter does not support pagination, see "count" and "offset" below for details on pagination support. |
| count | 7 | The number of results to retrieve (page size). The maximum count allowed is 500, see "offset" below on pagination support. |
| offset | 0 | The starting result number (0-based) to retrieve. Use offset and count together for pagination. Note that the current limit on the total number of results that can be retrieved (offset + count) is 7,500. We reserve the right to decrease or increase this limit based on system capacity and/or other factors. Please see the FAQ page on how to sign up to our email list to be notified of any changes or new features. |
| q | An 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. The parameter "ef" (see below) may also be used to specify the data fields to retrieve. The main difference is that the value of "df" is always a string (for display), while the value for "ef" could be a json object when the field value has a complex structure. |
| sf | NPI, name.full, provider_type, addr_practice.full | A comma-separated list of fields (or path to record json object) to be searched. |
| cf | NPI | The NPI ID, it's the unique record ID. |
| ef | A 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. The parameter "df" (see above) may also be used to specify the data fields to retrieve. The main difference is that the value of "df" is always a string (for display), while the value for "ef" could be a json object when the field value has a complex structure. |
NPI Field Descriptions
Important notes on the data fields
- In this API, the data is hierarchical and represented as a json object.
- A field (or data element) in such a json object may be referenced using the dotted path notion, for example, using name.last to refer to the last name element of the name object.
- Only the leaf level data elements, e.g., name.full (the full name string of the name object) are searchable.
- Both leaf data elements (e.g., name.last) and non-leaf data elements (e.g., the name object) can be returned (for display). However, when a data element is not a leaf data element, such a data element object will be returned as a json string.
- For more advanced users: in the dotted-path notion, if a given (level) object is an array, you may specify an index to select an item from the array. For example, a provider may have multiple liceses, the notion licenses[0].lic_number will select the license number for the first license.
| Field | Field Description |
|---|---|
| NPI | National Provider Identifier of the provider. |
| provider_type | The 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. |
| name.full | The full name string of the provider. |
| addr_practice.full | The full address string of the practice address. |
| licenses | A 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.taxonomy | The taxonomy object (with sub-fields) for the provider's corresponding license. For search, use its specific sub-fields. |
| licenses.taxonomy.code | The taxonomy code for the provider's corresponding license. |
| licenses.taxonomy.grouping | The taxonomy 'grouping' for the provider's corresponding license. |
| licenses.taxonomy.classification | The taxonomy 'classification' for the provider's corresponding license. |
| licenses.taxonomy.specialization | The taxonomy 'specialization' for the provider's corresponding license. |
| licenses.medicare | The medicare type object (with sub-fields) for the provider's corresponding license. For search, use its specific sub-fields. |
| licenses.medicare.spc_code | The medicare type specialty code for the provider's corresponding license. |
| licenses.medicare.type | The medicare provider type for the provider's corresponding license. |
| name | The name object (with sub-fields) of the provider. For search, use name.full or other specific sub-fields. |
| name.last | The last name of the provider. |
| name.first | The first name of the provider. |
| name.middle | The middle name of the provider. |
| name.credential | The credential (e.g., MD, RN) of the provider. |
| name.prefix | The prefix of the provider name. |
| name.suffix | The suffix of the provider name. |
| addr_practice | The provider's practice address object (with sub-fields). For search, use addr_practice.full or other specific sub-fields. |
| addr_practice.line1 | The line1 (street address) of the provider's practice address. |
| addr_practice.line2 | The line2 (e.g., suite#) of the provider's practice address. |
| addr_practice.city | The city of the provider's practice address. |
| addr_practice.state | The state of the provider's practice address. |
| addr_practice.zip | The zip code of the provider's practice address. |
| addr_practice.phone | The phone number for the provider's practice address. |
| addr_practice.fax | The fax number for the provider's practice address. |
| addr_practice.country | The country for the provider's practice address. |
| addr_mailing | The provider's mailing address object (with sub-fields). For search, use addr_mailing.full or other specific sub-fields. |
| addr_mailing.full | The full address string of the mailing address. |
| addr_mailing.line1 | The line1 (street address) of the provider's mailing address. |
| addr_mailing.line2 | The line2 (e.g., suite#) of the provider's mailing address. |
| addr_mailing.city | The city of the provider's mailing address. |
| addr_mailing.state | The state of the provider's mailing address. |
| addr_mailing.zip | The zip code of the provider's mailing address. |
| addr_mailing.phone | The phone number for the provider's mailing address. |
| addr_mailing.fax | The fax number for the provider's mailing address. |
| addr_mailing.country | The country for the provider's mailing address. |
| name_other | The provider's 'other name' object (with sub-fields). For search, use name_other.full or other specific sub-fields. |
| name_other.full | The full name string for the 'other name' of the provider. |
| name_other.last | The last name of the provider's other name. |
| name_other.first | The first name of the provider's other name. |
| name_other.middle | The middle name of the provider's other name. |
| name_other.credential | The credential (e.g., MD, RN) of the provider's other name. |
| name_other.prefix | The prefix of the provider's other name. |
| name_other.suffix | The suffix of the provider's other name. |
| other_ids | A list of other ids issued by various agencies/organizations, each with sub-fields. For search, use specific sub-fields. |
| other_ids.id | The id of the 'other id'. |
| other_ids.type | The type of the other id. |
| other_ids.issuer | The issuer of the other id. |
| other_ids.state | The state of the other id. |
| misc | An object with sub-fields for the other, misc data elements. |
| misc.auth_official | The 'authorized official' object for the provider, with sub-fields. For search, use specific sub-fields. |
| misc.auth_official.last | The last name of the provider's authorized official. |
| misc.auth_official.first | The first name of the provider's authorized official. |
| misc.auth_official.middle | The middle name of the provider's authorized official. |
| misc.auth_official.credential | The credential (e.g., MD, RN) of the provider's authorized official. |
| misc.auth_official.title | The title of the provider's authorized official. |
| misc.auth_official.prefix | The prefix of the provider's authorized official name. |
| misc.auth_official.suffix | The suffix of the provider's authorized official name. |
| misc.auth_official.phone | The phone of the provider's authorized official. |
| misc.replacement_NPI | The provider's replacement NPI number. |
| misc.EIN | The provider's EIN, rarely populated. |
| misc.enumeration_date | The enumeration data of the provider. |
| misc.last_update_date | The provider entry's last update date. |
| misc.is_sole_proprietor | The provider sole proprietor flag. |
| misc.is_org_subpart | The provider organization subpart flag. |
| misc.parent_LBN | The provider organization subpart legal business name. |
| misc.parent_TIN | The provider organization subpart TIN. |
Output format
Output for an API query is an array of the following elements:
- The total number of results on the server, which can be more than the number of results returned. This reported total number of results may also be significantly less than the actual number of results and is limited to 10,000, which may significantly improve the service response time.
- An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
- 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.
- 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.
- 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
| Query | Result | Description |
|---|---|---|
| https://clinicaltables.nlm.nih.gov/api/npi_org/v3/search?terms=john+bethesda | [9,["1518136233","1417038803","1619967726","1639349780","1881825495","1104129584","1376881441"],null,[["1518136233","JOHN M KELLY DDS PC","Dentist","4833 BETHESDA AVE SUITE 302, BETHESDA, MD 20814, US"],["1417038803","JOHN KEELING","Physician/Osteopathic Manipulative Medicine","8901 ROCKVILLE PIKE, BETHESDA, MD 20889, US"],["1619967726","JOHN P LYDON DPM","Ambulatory Surgical Center","5620 SHIELDS DR, BETHESDA, MD 20817, US"],["1639349780","JOHN P. LYDON, D.P.M.","Other Medical Supply Company","5620 SHIELDS DR, BETHESDA, MD 20817, US"],["1881825495","JOHN P LYDON DPM","Ambulatory Surgical Center","5620 SHIELDS DR, BETHESDA, MD 20817, US"],["1104129584","JOHN M LEPI MD INC","Physician/Obstetrics & Gynecology","945 BETHESDA DR SUITE 120, ZANESVILLE, OH 43701, US"],["1376881441","DRS ENSOR JOHNSON & LEWIS LLC","Dentist","11301 ROCKVILLE PIKE, NORTH BETHESDA, MD 20895, US"]]] | Returns 7 (out of 9 total) providers whose records match "john" and "bethesda". |
| https://clinicaltables.nlm.nih.gov/api/npi_org/v3/search?terms=williams&ef=other_ids | [3986,["1972780021","1245441963","1184895542","1083793012","1346462439","1922269810","1871804989"],{"other_ids":[[{"state":"OH","type":"02","id":"E93946"},{"state":"OH","type":"05","id":"0868691"},{"state":"OH","type":"06","id":"WI0697765"}],[{"state":"TN","type":"05","id":"3677135"},{"state":"TN","type":"02","id":"T74523"},{"state":"TN","type":"04","id":"3677135","issuer":"GROUP"}],null,null,[{"state":"TX","type":"05","id":"F50016386"}],null,null]},[["1972780021","WILLIAMS & WILLIAMS DO INC","Physician/Family Practice","3409 HOLLAND SYLVANIA RD, TOLEDO, OH 43615, US"],["1245441963","WILLIAMS & WILLIAMS CHIROPRACTIC CLINIC","Chiropractic","30 LYNOAK CV, JACKSON, TN 38305, US"],["1184895542","WILLIAMS AND WILLIAMS LLC","Physical Therapist in Private Practice","790 HOLLYANN CT, TWIN FALLS, ID 83301, US"],["1083793012","BERNARD WILLIAMS","Physician/Emergency Medicine","305 LANGDON ST, SOMERSET, KY 42503, US"],["1346462439","REGINA WILLIAMS","Residential Treatment Facility, Physical Disabilities","3807 WILLOWWOOD BLVD, SAN ANTONIO, TX 78219, US"],["1922269810","DWIGHT WILLIAMS","Certified Registered Nurse Anesthetist (CRNA)","608 N KEY AVE, LAMPASAS, TX 76550, US"],["1871804989","SONYA WILLIAMS","Case Management","3481PINEBROOK DR, DALLAS, TX 75241, US"]]] | Returns 7 (out of 3,986 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:
- NPI (National Provider Identifier) records from CMS (Centers for Medicare & Medicaid Services)
- Health Care Provider Taxonomy ("the taxonomy" hereafter) from NUCC (National Uniform Claim Committee)
- Crosswalk Medicare Provider/Supplier to Healthcare Provider Taxonomy ("the crosswalk" hereafter) from CMS.
The data construction starts from an NPI record:
- Filter out records that have been deactivated.
- Minor formatting on phone numbers, zip codes, credential texts, etc.
- 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.
- Construct full address strings from address "parts" (e.g., line1, line2, city) in the NPI record.
- 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.
- 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.
- 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.