Providers

Three endpoints cover the core provider use cases: looking up a known NPI, searching by name or specialty, and finding providers near a location.

NPI lookup

Retrieve a single provider by NPI number. This is the fastest and most precise query.

GET /v1/providers/{npi}

Path parameters

Parameter	Type	Description
npi required	string	10-digit NPI number. The API validates format and check digit before querying the database.

Response

Field	Type	Description
npi	string	The NPI number.
entity_type	string	`individual` or `organization`.
name	object\|null	Name fields for individuals (`first`, `middle`, `last`, `credential`). Null for organizations.
organization_name	string\|null	Organization name. Null for individuals.
status	string	`active` or `deactivated`.
enumeration_date	string	Date the NPI was assigned (ISO 8601).
last_updated	string	Date the NPPES record was last updated (ISO 8601).
deactivation_date	string\|null	Date deactivated, if applicable.
primary_taxonomy	object\|null	Primary taxonomy code and description (`code`, `description`).
practice_address	object\|null	Primary practice location (`address_1`, `address_2`, `city`, `state`, `postal_code`, `country`).

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/1003000126"

$ch = curl_init('https://api.npilayer.com/v1/providers/1003000126');
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);
$provider = $body['data'];

const r = await fetch('https://api.npilayer.com/v1/providers/1003000126', {
  headers: { 'Authorization': `Bearer ${process.env.NPILAYER_API_KEY}` }
});
const { data: provider } = await r.json();

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

{
  "data": {
    "npi": "1003000126",
    "entity_type": "individual",
    "name": {
      "first": "Jane",
      "middle": "A",
      "last": "Smith",
      "credential": "MD"
    },
    "organization_name": null,
    "status": "active",
    "enumeration_date": "2008-04-14",
    "last_updated": "2026-08-21",
    "deactivation_date": null,
    "primary_taxonomy": {
      "code": "207RC0000X",
      "description": "Cardiovascular Disease Physician"
    },
    "practice_address": {
      "address_1": "123 Main St",
      "address_2": null,
      "city": "Traverse City",
      "state": "MI",
      "postal_code": "49684",
      "country": "US"
    }
  },
  "meta": {
    "source": "CMS NPPES"
  }
}

Provider search

Search for providers using name, location, specialty, and other filters. At least one filter parameter is recommended — an empty query returns paginated results across all providers.

GET /v1/providers/search

Query parameters

Parameter	Type	Description
name	string	Partial match against first name, last name, or organization name.
first_name	string	Filter by first name (individuals only).
last_name	string	Filter by last name (individuals only).
organization	string	Filter by organization name.
entity_type	string	`individual` or `organization`.
city	string	Filter by practice city.
state	string	Two-letter state abbreviation (e.g. `MI`).
zip	string	5-digit ZIP code of the practice address.
taxonomy	string	Exact NUCC taxonomy code (e.g. `207RC0000X`).
specialty	string	Partial text match against taxonomy display name (e.g. `cardiology`).
limit	integer	Results per page. Default `25`, maximum `100`.
page	integer	Page number, 1-based. Default `1`.

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/search?last_name=smith&state=MI&specialty=cardiology"

$params = http_build_query([
    'last_name' => 'smith',
    'state'     => 'MI',
    'specialty' => 'cardiology',
]);
$ch = curl_init('https://api.npilayer.com/v1/providers/search?' . $params);
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 params = new URLSearchParams({
  last_name: 'smith',
  state: 'MI',
  specialty: 'cardiology',
});
const r = await fetch(
  `https://api.npilayer.com/v1/providers/search?${params}`,
  { headers: { 'Authorization': `Bearer ${process.env.NPILAYER_API_KEY}` } }
);
const { data, meta } = await r.json();

import os, requests
r = requests.get(
    'https://api.npilayer.com/v1/providers/search',
    params={'last_name': 'smith', 'state': 'MI', 'specialty': 'cardiology'},
    headers={'Authorization': f"Bearer {os.environ['NPILAYER_API_KEY']}"}
)
body = r.json()
providers = body['data']
meta = body['meta']

{
  "data": [
    {
      "npi": "1003000126",
      "entity_type": "individual",
      "name": {
        "first": "Jane",
        "middle": null,
        "last": "Smith",
        "credential": "MD"
      },
      "organization_name": null,
      "status": "active",
      "primary_taxonomy": {
        "code": "207RC0000X",
        "description": "Cardiovascular Disease Physician"
      },
      "city": "Traverse City",
      "state": "MI"
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "limit": 25,
    "total": 1
  }
}

Geographic search

Find providers within a radius of a ZIP code or GPS coordinates. Results are ordered by distance ascending and include a distance_miles field. Location resolution is ZIP-centroid based — distances are approximate.

GET /v1/providers/nearby

Query parameters

Parameter	Type	Description
zip required*	string	5-digit ZIP code to search around. Required unless `lat`/`lng` are provided.
lat required*	number	Latitude in decimal degrees. Provide with `lng` as an alternative to `zip`.
lng required*	number	Longitude in decimal degrees. Provide with `lat` as an alternative to `zip`.
radius	number	Search radius in miles. Default `25`.
taxonomy	string	Exact NUCC taxonomy code.
specialty	string	Partial text match against taxonomy display name.
limit	integer	Results per page. Default `25`, maximum `100`.
page	integer	Page number, 1-based. Default `1`.

* Provide either zip or both lat and lng. Providing none returns a 400 invalid_location error.

# By ZIP code
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/nearby?zip=49684&specialty=cardiology&radius=25"

# By coordinates
curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npilayer.com/v1/providers/nearby?lat=44.7631&lng=-85.6206&radius=50"

$params = http_build_query([
    'zip'       => '49684',
    'specialty' => 'cardiology',
    'radius'    => 25,
]);
$ch = curl_init('https://api.npilayer.com/v1/providers/nearby?' . $params);
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 params = new URLSearchParams({
  zip: '49684',
  specialty: 'cardiology',
  radius: '25',
});
const r = await fetch(
  `https://api.npilayer.com/v1/providers/nearby?${params}`,
  { headers: { 'Authorization': `Bearer ${process.env.NPILAYER_API_KEY}` } }
);
const { data, meta } = await r.json();

import os, requests
r = requests.get(
    'https://api.npilayer.com/v1/providers/nearby',
    params={'zip': '49684', 'specialty': 'cardiology', 'radius': 25},
    headers={'Authorization': f"Bearer {os.environ['NPILAYER_API_KEY']}"}
)
body = r.json()
providers = body['data']

{
  "data": [
    {
      "npi": "1003000126",
      "entity_type": "individual",
      "name": {
        "first": "Jane",
        "middle": null,
        "last": "Smith",
        "credential": "MD"
      },
      "organization_name": null,
      "status": "active",
      "primary_taxonomy": {
        "code": "207RC0000X",
        "description": "Cardiovascular Disease Physician"
      },
      "city": "Traverse City",
      "state": "MI",
      "distance_miles": 3.8
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "limit": 25,
    "radius_miles": 25,
    "center": {
      "zip": "49684",
      "lat": 44.7631,
      "lng": -85.6206
    }
  }
}

Geographic search uses ZIP-centroid coordinates, not exact street addresses. Distances are approximate and suitable for discovery but should not be treated as precise routing distances.