Taxonomies

Provider taxonomy codes come from the NUCC Health Care Provider Taxonomy code set. Each provider may have one or more taxonomy codes; one is designated primary. Use taxonomy codes to filter provider searches precisely, or use the specialty parameter on provider endpoints for partial-text matching.

List taxonomies

Returns all active taxonomy codes, paginated.

GET /v1/taxonomies

Query parameters

Parameter	Type	Description
limit	integer	Results per page. Default `25`.
page	integer	Page number, 1-based. Default `1`.

Response fields

Field	Type	Description
code	string	NUCC taxonomy code (e.g. `207RC0000X`).
grouping	string\|null	Top-level grouping category.
classification	string\|null	Classification within the grouping.
specialization	string\|null	Specialization within the classification, if applicable.
display_name	string	Human-readable name (e.g. `Cardiovascular Disease Physician`).
definition	string\|null	NUCC definition text, if available.
active	boolean	`true` for codes currently in the NUCC taxonomy.

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/taxonomies?limit=10"

$ch = curl_init('https://api.npilayer.com/v1/taxonomies?limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NPILAYER_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$taxonomies = $body['data'];

const r = await fetch('https://api.npilayer.com/v1/taxonomies?limit=10', {
  headers: { 'Authorization': `Bearer ${process.env.NPILAYER_API_KEY}` }
});
const { data: taxonomies, meta } = await r.json();

import os, requests
r = requests.get(
    'https://api.npilayer.com/v1/taxonomies',
    params={'limit': 10},
    headers={'Authorization': f"Bearer {os.environ['NPILAYER_API_KEY']}"}
)
taxonomies = r.json()['data']

{
  "data": [
    {
      "code": "207RC0000X",
      "grouping": "Allopathic & Osteopathic Physicians",
      "classification": "Internal Medicine",
      "specialization": "Cardiovascular Disease",
      "display_name": "Cardiovascular Disease Physician",
      "definition": null,
      "active": true
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "limit": 10,
    "total": 865
  }
}

Search taxonomies

Search taxonomy codes by display name or classification. Useful for building specialty-picker UI or resolving a plain-language specialty term to a taxonomy code before calling the provider search endpoint.

GET /v1/taxonomies/search

Query parameters

Parameter	Type	Description
q required	string	Partial text to match against taxonomy display name and classification.
limit	integer	Results per page. Default `25`.
page	integer	Page number, 1-based. Default `1`.

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/taxonomies/search?q=cardiology"

$ch = curl_init('https://api.npilayer.com/v1/taxonomies/search?q=cardiology');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NPILAYER_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

const r = await fetch(
  'https://api.npilayer.com/v1/taxonomies/search?q=cardiology',
  { headers: { 'Authorization': `Bearer ${process.env.NPILAYER_API_KEY}` } }
);
const { data } = await r.json();

import os, requests
r = requests.get(
    'https://api.npilayer.com/v1/taxonomies/search',
    params={'q': 'cardiology'},
    headers={'Authorization': f"Bearer {os.environ['NPILAYER_API_KEY']}"}
)
results = r.json()['data']

{
  "data": [
    {
      "code": "207RC0000X",
      "grouping": "Allopathic & Osteopathic Physicians",
      "classification": "Internal Medicine",
      "specialization": "Cardiovascular Disease",
      "display_name": "Cardiovascular Disease Physician",
      "definition": null,
      "active": true
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "limit": 25,
    "total": 1
  }
}

Using taxonomy codes in provider search

Once you have a taxonomy code, use it in provider search or geographic search:

# Exact taxonomy code match
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/search?taxonomy=207RC0000X&state=MI"

# Geographic search with taxonomy
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/nearby?zip=49684&taxonomy=207RC0000X&radius=25"