API Documentation

Everything you need to integrate NPI lookup and healthcare provider verification into your application.

Authentication

All API requests require an API key passed in the X-API-Key header.

Getting a key

Sign up on the home page with your email to receive a free API key instantly. Keys start with the prefix pv_.

Header format

X-API-Key: pv_your_api_key_here

Base URL

https://api.clearnpi.io/v1

All endpoint paths below are relative to this base URL.

Endpoints

GET/v1/provider/{npi}Lookup a single provider by NPI
GET/v1/provider/searchSearch providers with filters
POST/v1/provider/batchBatch verify multiple NPIs
GET/v1/taxonomyList or search taxonomy codes
POST/v1/keys/createCreate a free API key
GET/v1/provider/{npi}Lookup a single provider by NPI

Returns the full provider record for a given NPI, including status, address, specialty, OIG exclusion status, and state licenses.

Path parameters

ParameterTypeRequiredDescription
npistringYes10-digit National Provider Identifier

Response

{
  "npi": "1234567890",
  "entity_type": "individual",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "organization_name": null,
  "gender": "F",
  "specialty": "Family Medicine",
  "taxonomy_code": "207Q00000X",
  "address_line1": "100 Medical Center Dr",
  "city": "Los Angeles",
  "state": "CA",
  "zip_code": "90001",
  "phone": "310-555-0100",
  "latitude": 34.0522,
  "longitude": -118.2437,
  "status": "active",
  "enumeration_date": "2005-04-15",
  "oig_excluded": false,
  "oig_exclusion_date": null,
  "licenses": [
    {
      "state": "CA",
      "license_number": "A123456",
      "license_type": "MD",
      "status": "active",
      "expiration_date": "2026-12-31",
      "last_verified": "2026-03-01"
    }
  ]
}

Example

curl -H "X-API-Key: pv_your_key" \
  https://api.clearnpi.io/v1/provider/1234567890
GET/v1/provider/searchSearch providers with filters

Search the provider database by name, specialty, state, entity type, or status. Returns paginated results.

Query parameters

ParameterTypeRequiredDescription
namestringNoProvider name (partial match)
specialtystringNoMedical specialty
statestringNo2-letter state code
entity_typestringNo"individual" or "organization"
statusstringNo"active", "inactive", or "deactivated"
pageintegerNoPage number (default: 1)
per_pageintegerNoResults per page (default: 20, max: 100)

Response

{
  "total": 142,
  "page": 1,
  "per_page": 20,
  "results": [
    { /* Provider object */ },
    ...
  ]
}

Example

curl -H "X-API-Key: pv_your_key" \
  "https://api.clearnpi.io/v1/provider/search?name=johnson&state=CA&per_page=10"
POST/v1/provider/batchBatch verify multiple NPIs

Verify up to 100 NPIs in a single request. Returns each provider's verification status and data.

Request body

ParameterTypeRequiredDescription
npisstring[]YesArray of NPI strings (max 100)

Request example

{
  "npis": ["1234567890", "0987654321", "5556667778"]
}

Response

{
  "total_requested": 3,
  "total_found": 2,
  "results": [
    {
      "npi": "1234567890",
      "found": true,
      "provider": { /* Provider object */ },
      "error": null
    },
    {
      "npi": "0987654321",
      "found": true,
      "provider": { /* Provider object */ },
      "error": null
    },
    {
      "npi": "5556667778",
      "found": false,
      "provider": null,
      "error": "NPI not found"
    }
  ],
  "response_time_ms": 42
}

Example

curl -X POST -H "X-API-Key: pv_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis":["1234567890","0987654321"]}' \
  https://api.clearnpi.io/v1/provider/batch
GET/v1/taxonomyList or search taxonomy codes

Returns healthcare provider taxonomy codes. Optionally filter by search term. No API key required for this endpoint.

Query parameters

ParameterTypeRequiredDescription
searchstringNoFilter taxonomy codes by keyword

Response

[
  {
    "code": "207Q00000X",
    "grouping": "Allopathic & Osteopathic Physicians",
    "classification": "Family Medicine",
    "specialization": null,
    "display_name": "Family Medicine"
  },
  ...
]

Example

curl "https://api.clearnpi.io/v1/taxonomy?search=cardiology"
POST/v1/keys/createCreate a free API key

Create a free-tier API key. No authentication required.

Request body

ParameterTypeRequiredDescription
emailstringYesYour email address
namestringNoKey name (default: "Default key")

Response

{
  "api_key": "pv_live_abc123...",
  "plan": "free"
}

Example

curl -X POST -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com"}' \
  https://api.clearnpi.io/v1/keys/create

Error Codes

StatusCodeDescription
400Bad RequestInvalid parameters — check required fields and format
401UnauthorizedMissing or invalid API key in the X-API-Key header
404Not FoundThe requested NPI does not exist in the database
429Too Many RequestsRate limit exceeded — slow down or upgrade your plan

Error response format

{
  "detail": "Invalid API key",
  "status_code": 401
}

Rate Limits

Rate limits are enforced per API key. When you exceed your limit, the API returns 429 Too Many Requests.

PlanRequests / minuteRequests / monthBatch size
Free101,00010 NPIs
Basic6050,00050 NPIs
Pro300500,000100 NPIs
EnterpriseUnlimitedUnlimited100 NPIs

Data Freshness

ClearNPI aggregates data from multiple federal and state sources. Here's how often each source is updated:

SourceDataUpdate frequency
NPPESNPI records, demographics, taxonomyWeekly (every Sunday)
OIG LEIEExclusion list — fraud, abuse flagsMonthly
State boardsLicense status, expiration datesVaries by state (daily to monthly)

SDKs & Integration

ClearNPI is a standard REST API that works with any HTTP client in any language. No proprietary SDK is required.

Quick start examples

JavaScript / TypeScript

const res = await fetch("https://api.clearnpi.io/v1/provider/1234567890", {
  headers: { "X-API-Key": "pv_your_key" },
});
const provider = await res.json();

Python

import requests

resp = requests.get(
    "https://api.clearnpi.io/v1/provider/1234567890",
    headers={"X-API-Key": "pv_your_key"},
)
provider = resp.json()

cURL

curl -H "X-API-Key: pv_your_key" \
  https://api.clearnpi.io/v1/provider/1234567890