NPI Portal NPI Lookup & Verification

API Documentation

Base URL https://api.npiportal.com. The machine-readable spec lives at /openapi.json (OpenAPI 3.1).

Authentication

Every /v1 request needs an API key, sent either as Authorization: Bearer npk_… or x-api-key: npk_…. Keys are issued per account — see plans & signup. Keys are stored hashed; treat yours like a password.

Rate limits & quotas

Limits depend on your tier (Free 5/min · Starter 60/min · Pro 300/min · Business 1,000/min, with monthly quotas of 1k/50k/500k/5M). Every response carries x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and x-quota-monthly-remaining headers. Exceeding a limit returns 429 with an explanatory error body.

Errors

Errors return { "error": { "code", "message" } } with conventional HTTP status codes: 400 bad input, 401 missing/invalid key, 404 not found, 422 checksum failure, 429 rate limited.

GET /v1/npi/{number}

Look up a single NPI. Returns the full normalized NPPES record: names, credential, taxonomies with license numbers, practice and mailing addresses, other identifiers (Medicaid, legacy Medicare), enumeration and deactivation dates. The `source` field tells you whether the record came from our indexed snapshot (kv/r2) or the live registry (nppes-live).

Request

curl https://api.npiportal.com/v1/npi/1234567893 \
  -H "Authorization: Bearer npk_your_key"

Response

{
  "npi": "1234567893",
  "source": "r2",
  "record": {
    "npi": "1234567893",
    "entityType": 1,
    "firstName": "JANE",
    "lastName": "SMITH",
    "credential": "MD",
    "taxonomies": [
      { "code": "207Q00000X", "primary": true, "license": "036.123456", "licenseState": "IL" }
    ],
    "practiceAddress": { "line1": "123 MAIN ST", "city": "CHICAGO", "state": "IL", "zip": "60601", "phone": "3125550100" },
    "enumerationDate": "2007-05-23",
    "lastUpdateDate": "2024-01-15",
    "deactivationDate": null
  }
}

GET /v1/npi/search

Search providers. Query parameters: `q` (free text name or NPI), `first_name`, `last_name`, `organization`, `state`, `city`, `zip`, `taxonomy`, `entity_type` (1 or 2), `limit` (max 100), `offset`. At least one criterion is required. Returns slim result rows; follow up with the single-NPI endpoint for full records.

Request

curl "https://api.npiportal.com/v1/npi/search?last_name=smith&state=IL&limit=5" \
  -H "x-api-key: npk_your_key"

Response

{
  "total": 1204,
  "count": 5,
  "offset": 0,
  "source": "d1",
  "results": [ { "npi": "1234567893", "name": "JANE SMITH", "entityType": 1, "state": "IL", "taxonomyCode": "207Q00000X" } ]
}

POST /v1/npi/batch

Batch-verify up to 100 NPIs. Send `{"npis": ["…", …]}` (max 100). Each result reports `status`: `active`, `deactivated`, `not_found`, or `invalid` (checksum failure), plus name, primary taxonomy, and state. One batch call counts as 10 requests against your quota. Built for credentialing sweeps and claims scrubbing.

Request

curl -X POST https://api.npiportal.com/v1/npi/batch \
  -H "Authorization: Bearer npk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis": ["1234567893", "1679576722"]}'

Response

{
  "count": 2,
  "results": [
    { "npi": "1234567893", "status": "active", "entityType": 1, "name": "JANE SMITH", "primaryTaxonomy": "207Q00000X", "state": "IL" },
    { "npi": "1679576722", "status": "active", "entityType": 2, "name": "EXAMPLE HOSPITAL", "primaryTaxonomy": "282N00000X", "state": "NY" }
  ]
}

GET /v1/npi/validate/{number}

Checksum-validate an NPI. Pure ISO/Luhn check-digit validation (prefix 80840 + first 9 digits) — no registry lookup, so it cannot tell you whether the NPI was ever issued. Use it to reject malformed input before a lookup.

Request

curl https://api.npiportal.com/v1/npi/validate/1234567893 \
  -H "x-api-key: npk_your_key"

Response

{
  "input": "1234567893",
  "normalized": "1234567893",
  "wellFormed": true,
  "checksumValid": true,
  "valid": true,
  "reason": null
}

GET /v1/taxonomy/{code}

Decode a taxonomy code. Returns the NUCC record for a 10-character taxonomy code: grouping, classification, specialization, plain-English definition, and the number of providers using it as their primary taxonomy in the latest snapshot.

Request

curl https://api.npiportal.com/v1/taxonomy/207Q00000X \
  -H "x-api-key: npk_your_key"

Response

{
  "code": "207Q00000X",
  "grouping": "Allopathic & Osteopathic Physicians",
  "classification": "Family Medicine",
  "specialization": null,
  "displayName": "Family Medicine",
  "specialtySlug": "family-medicine",
  "providerCount": 118432
}