API Documentation

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

https://api.clearnpi.io/v1

All endpoint paths below are relative to this base URL.

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

Path parameters

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"
    }
  ]
}

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

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

Query parameters

Response

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

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

Returns state license details for a given provider, including license number, status, and expiration date.

Path parameters

Response

{
  "npi": "1234567890",
  "licenses": [
    {
      "state": "CA",
      "license_number": "A123456",
      "license_type": "MD",
      "status": "active",
      "expiration_date": "2026-12-31",
      "last_verified": "2026-03-01"
    }
  ]
}

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

Check whether a provider appears on the OIG List of Excluded Individuals/Entities (LEIE). Returns exclusion status and date if applicable.

Path parameters

Response

{
  "npi": "1234567890",
  "oig_excluded": false,
  "exclusion_date": null
}

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

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

Request body

Request example

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

Response

{
  "total_requested": 3,
  "total_found": 2,
  "results": [
    {
      "npi": "1234567890",
      "found": true,
      "provider": {
        "npi": "1234567890",
        "entity_type": "individual",
        "first_name": "Sarah",
        "last_name": "Johnson",
        "organization_name": null,
        "specialty": "Family Medicine",
        "taxonomy_code": "207Q00000X",
        "city": "Los Angeles",
        "state": "CA",
        "status": "active",
        "oig_excluded": false,
        "licenses": [
          { "state": "CA", "status": "active", "expiration_date": "2026-12-31" }
        ]
      },
      "error": null
    },
    {
      "npi": "5556667778",
      "found": false,
      "provider": null,
      "error": "NPI not found"
    }
  ],
  "response_time_ms": 42
}

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

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

Query parameters

Response

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

curl "https://api.clearnpi.io/v1/taxonomy?search=cardiology"

Subscribe to receive a webhook notification when a provider's license is approaching its expiration date.

Request body

Response

{
  "status": "subscribed",
  "npi": "1234567890",
  "callback_url": "https://yourapp.com/webhook"
}

curl -X POST -H "X-API-Key: pv_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npi":"1234567890","callback_url":"https://yourapp.com/webhook","days_before":30}' \
  https://api.clearnpi.io/v1/webhooks/expiry

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

Request body

Response

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

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

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

Rate limits reset daily at midnight UTC. Exceeding your limit returns 429 Too Many Requests. The X-RateLimit-Remaining header shows your remaining calls for the day.

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

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

Quick start examples

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

import requests

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

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