API documentation

Request with 3–5 NPIs

Send npis as a JSON array (1–50 strings). Each element is looked up independently; the HTTP response is always 200 when the batch is accepted (per-item errors appear inside data[]).

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"npis":["1003000126","1932100864","1851789159","1234567893","1467560003"]}' \
  "https://healthproviderapi.com/api/v1/npi/bulk"

Mixed found / not_found response

Each row includes status (found, not_found, upstream_error, or quota_exceeded). Found rows include the same ProviderData object as single lookup.

{
  "data": [
    {
      "npi": "1003000126",
      "status": "found",
      "provider": { "npi": "1003000126", "entityType": "NPI-1" },
      "cached": true,
      "requestId": "req_bulk01_00",
      "error": null
    },
    {
      "npi": "1932100864",
      "status": "not_found",
      "provider": null,
      "cached": false,
      "requestId": "req_bulk01_01",
      "error": null
    },
    {
      "npi": "1851789159",
      "status": "upstream_error",
      "provider": null,
      "cached": false,
      "requestId": "req_bulk01_02",
      "error": {
        "code": "upstream_unavailable",
        "message": "The upstream provider registry is temporarily unavailable."
      }
    }
  ],
  "meta": {
    "requestId": "req_bulk01",
    "counts": {
      "requested": 3,
      "found": 1,
      "notFound": 1,
      "upstreamErrors": 1,
      "quotaExceeded": 0,
      "cacheHits": 1
    }
  }
}

Quota metering (per item)

Each found and each not_found item consumes one monthly credit from your shared pool (same as lookup 200/404). upstream_error rows do not bill. If the batch would exceed remaining quota, later items may return quota_exceeded without calling upstream. See meta.counts in the response.

CSV → JSON preparation

Export a single column of ten-digit NPIs from your spreadsheet (no hyphens). In a script or spreadsheet formula, build the request body:

{
  "npis": [
    "1003000126",
    "1932100864",
    "1851789159"
  ]
}

Tip: strip whitespace and validate length locally before POSTing. For large rosters, chunk into batches of 50 and pace requests to stay within burst rate limits.

Enrichment on bulk

enrichment=quality_freshness is available on single lookup and provider search (Growth+ plans). It is not supported on POST /api/v1/npi/bulk today—run enrichment on individual lookups when you need freshness or completeness signals for specific rows.

Request format

Pass enrichment as a query parameter on search, or as a query parameter or HTTP header on single lookup (Growth and Pro plans). Bulk lookup does not accept enrichment—use single lookup for enriched rows. Factors: completeness, quality_score, freshness, or the preset quality_freshness (all three). Combine search factors with commas, e.g. enrichment=completeness,freshness.

GET /api/v1/providers/search?last_name=Smith&enrichment=quality_freshness
Authorization: Bearer YOUR_KEY

GET /api/v1/npi/1003000126?enrichment=quality_score
Authorization: Bearer YOUR_KEY

curl -sS \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "enrichment: quality_score" \
  "https://healthproviderapi.com/api/v1/npi/1003000126"

Credit cost

Each enrichment request costs 2 credits total, regardless of how many factors you request. Non-enriched requests cost 1 credit as before.

Response fields

When enrichment is applied, each provider includes an enrichment object with dataQuality.score (0-100), dataQuality.completeness.* flags, and freshness.* fields. The meta.enrichment request-level object shows applied factors and credit cost.

Not a verification

Enrichment signals are derived from NPPES data only and are not legal or clinical verification. Use enrichment to rank/filter providers, not to make compliance determinations.