{
  "info": {
    "name": "Health Provider API",
    "description": "NPPES-backed NPI Registry API: single lookup by 10-digit NPI (`GET /api/v1/npi/{npi}`), bulk lookup (`POST /api/v1/npi/bulk`), and directory search (`GET /api/v1/providers/search`).\n\n## Getting Started\n1. Sign up at https://healthproviderapi.com and create an API key from your dashboard\n2. Copy the API key — it is only shown once\n3. Set the `apiKey` variable in this collection to your key\n4. Optionally set the `npi` variable (10 digits, no hyphens) for the NPI Lookup request\n5. Send requests with `Authorization: Bearer YOUR_API_KEY` to the NPI Lookup, Bulk NPI lookup, or Provider search folder\n\n## Authentication\nBearer API key on every authenticated request.\n\n## Rate Limits\nBurst rate limits apply per API key (default: 300 requests/minute).\n\n## Quotas\nMonthly credits are shared across lookup and search. Each **HTTP 200** and each **HTTP 404** (`npi_not_found`) uses **one** credit; **502** upstream errors do not. Bulk lookup meters per item (`found`/`not_found` charge; `upstream_error` does not). **Enrichment requests** cost **2 credits total** when the `enrichment` query parameter or header is used (Growth/Pro plans only). See `X-Quota-Limit` and `X-Quota-Remaining`.\n\n\n## Enrichment (Growth/Pro only)\nAdd `enrichment` query param to search or header to single lookup. Values: `completeness`, `quality_score`, `freshness`, or `quality_freshness` (preset for all three). Each enrichment request costs 2 credits total, regardless of factors requested.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://healthproviderapi.com"
    },
    {
      "key": "apiKey",
      "value": "YOUR_API_KEY_HERE"
    },
    {
      "key": "npi",
      "value": "1003000126"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "NPI Lookup",
      "request": {
        "name": "Look up provider by NPI",
        "description": "Returns normalized provider data for the given 10-digit NPI number including name, taxonomy, addresses, and enumeration details.\n\n## NPI Format\n- Must be exactly 10 digits (no hyphens)\n- Leading/trailing whitespace is trimmed automatically\n- Invalid format returns HTTP 400 with code `invalid_npi` (before auth; no quota headers)\n\n## Quota\n- HTTP **200** and HTTP **404** (`npi_not_found`) each consume **one** monthly credit\n- HTTP **502** (`upstream_unavailable`) does **not** consume a credit\n\n## Response Caching\n- Cache hit: response returned from cache, no upstream NPPES call\n- Cache miss: fresh lookup from NPPES, response cached\n- Stale: cached but past TTL, returned while revalidating upstream\n- `meta.cached` is true when `X-Cache-Status` is `hit` or `stale`",
        "method": "GET",
        "url": {
          "raw": "{{baseUrl}}/api/v1/npi/{{npi}}",
          "host": ["{{baseUrl}}"],
          "path": ["api", "v1", "npi", "{{npi}}"]
        },
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{apiKey}}",
            "description": "Your API key (Bearer token)"
          }
        ]
      },
      "response": [
        {
          "name": "200 OK — Provider found",
          "status": "OK",
          "code": 200,
          "body": "{\n  \"data\": {\n    \"npi\": \"1003000126\",\n    \"entityType\": \"NPI-1\",\n    \"status\": \"active\",\n    \"name\": {\n      \"full\": \"JOHN SMITH, M.D.\",\n      \"first\": \"JOHN\",\n      \"middle\": null,\n      \"last\": \"SMITH\",\n      \"prefix\": null,\n      \"credential\": \"M.D.\"\n    },\n    \"primaryTaxonomy\": {\n      \"code\": \"208M00000X\",\n      \"description\": \"Hospitalist\",\n      \"state\": \"DC\",\n      \"license\": \"MD600003480\"\n    },\n    \"taxonomies\": [],\n    \"mailingAddress\": {},\n    \"practiceLocations\": [],\n    \"enumerationDate\": \"2007-08-31\",\n    \"lastUpdated\": \"2026-05-01\",\n    \"source\": { \"name\": \"NPPES\", \"version\": \"2.1\" }\n  },\n  \"meta\": {\n    \"requestId\": \"req_abc123\",\n    \"cached\": true\n  }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123", "description": "Unique request ID for debugging" },
            { "key": "X-Cache-Status", "value": "hit | miss | stale", "description": "Whether the response was served from cache" },
            { "key": "X-Quota-Limit", "value": "1000", "description": "Total monthly lookups allowed on your plan" },
            { "key": "X-Quota-Remaining", "value": "999", "description": "Remaining lookups this billing period" },
            { "key": "X-RateLimit-Limit", "value": "300", "description": "Burst rate limit per minute" },
            { "key": "X-RateLimit-Remaining", "value": "299", "description": "Requests remaining in current window" },
            { "key": "X-RateLimit-Reset", "value": "1747800060", "description": "Unix timestamp when the rate limit window resets" }
          ]
        },
        {
          "name": "400 Bad Request — Invalid NPI",
          "status": "Bad Request",
          "code": 400,
          "body": "{\n  \"error\": {\n    \"code\": \"invalid_npi\",\n    \"message\": \"NPI must be a 10-digit number.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123", "description": "Only standard header on 400 — no quota or rate-limit headers" }
          ]
        },
        {
          "name": "401 Unauthorized — Invalid API Key",
          "status": "Unauthorized",
          "code": 401,
          "body": "{\n  \"error\": {\n    \"code\": \"invalid_api_key\",\n    \"message\": \"Missing or invalid API key.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" }
          ]
        },
        {
          "name": "403 Forbidden — Quota Exceeded",
          "status": "Forbidden",
          "code": 403,
          "body": "{\n  \"error\": {\n    \"code\": \"quota_exceeded\",\n    \"message\": \"Monthly lookup quota has been exceeded.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" },
            { "key": "X-Quota-Limit", "value": "1000" },
            { "key": "X-Quota-Remaining", "value": "0" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "403 Forbidden — Subscription Inactive",
          "status": "Forbidden",
          "code": 403,
          "body": "{\n  \"error\": {\n    \"code\": \"subscription_inactive\",\n    \"message\": \"Your subscription is not active.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "404 Not Found — NPI Not Found",
          "status": "Not Found",
          "code": 404,
          "body": "{\n  \"error\": {\n    \"code\": \"npi_not_found\",\n    \"message\": \"No provider found for the supplied NPI.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" },
            { "key": "X-Cache-Status", "value": "miss", "description": "Typically miss when NPI is unknown" },
            { "key": "X-Quota-Limit", "value": "1000" },
            { "key": "X-Quota-Remaining", "value": "999", "description": "After meter — one credit consumed for not_found" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "429 Too Many Requests — Rate Limited",
          "status": "Too Many Requests",
          "code": 429,
          "body": "{\n  \"error\": {\n    \"code\": \"rate_limited\",\n    \"message\": \"Too many requests for this API key. Slow down and retry after the reset time.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "0" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "500 Internal Server Error",
          "status": "Internal Server Error",
          "code": 500,
          "body": "{\n  \"error\": {\n    \"code\": \"internal_error\",\n    \"message\": \"An unexpected error occurred. Please try again later.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" }
          ]
        },
        {
          "name": "502 Bad Gateway — Upstream Unavailable",
          "status": "Bad Gateway",
          "code": 502,
          "body": "{\n  \"error\": {\n    \"code\": \"upstream_unavailable\",\n    \"message\": \"The upstream provider registry is temporarily unavailable.\"\n  },\n  \"meta\": { \"requestId\": \"req_abc123\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_abc123" },
            { "key": "X-Quota-Limit", "value": "1000", "description": "Unchanged — 502 does not consume quota" },
            { "key": "X-Quota-Remaining", "value": "1000" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "298" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        }
      ]
    },
    {
      "name": "Bulk NPI lookup",
      "request": {
        "name": "Bulk look up providers by NPI",
        "description": "Submit 1-50 NPIs in one request body. Each item returns its own status (`found`, `not_found`, `upstream_error`, or `quota_exceeded`) in a single HTTP 200 response. Duplicate NPIs are allowed and metered independently.",
        "method": "POST",
        "url": {
          "raw": "{{baseUrl}}/api/v1/npi/bulk",
          "host": ["{{baseUrl}}"],
          "path": ["api", "v1", "npi", "bulk"]
        },
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{apiKey}}",
            "description": "Your API key (Bearer token)"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"npis\": [\n    \"1003000126\",\n    \"1932100864\",\n    \"1851789159\"\n  ]\n}"
        }
      },
      "response": [
        {
          "name": "200 OK — Mixed per-item outcomes",
          "status": "OK",
          "code": 200,
          "body": "{\n  \"data\": [\n    {\n      \"npi\": \"1003000126\",\n      \"status\": \"found\",\n      \"provider\": { \"npi\": \"1003000126\" },\n      \"cached\": true,\n      \"requestId\": \"req_bulk01_00\",\n      \"error\": null\n    },\n    {\n      \"npi\": \"1932100864\",\n      \"status\": \"not_found\",\n      \"provider\": null,\n      \"cached\": false,\n      \"requestId\": \"req_bulk01_01\",\n      \"error\": null\n    },\n    {\n      \"npi\": \"1851789159\",\n      \"status\": \"upstream_error\",\n      \"provider\": null,\n      \"cached\": false,\n      \"requestId\": \"req_bulk01_02\",\n      \"error\": {\n        \"code\": \"upstream_unavailable\",\n        \"message\": \"The upstream provider registry is temporarily unavailable.\"\n      }\n    }\n  ],\n  \"meta\": {\n    \"requestId\": \"req_bulk01\",\n    \"counts\": {\n      \"requested\": 3,\n      \"found\": 1,\n      \"notFound\": 1,\n      \"upstreamErrors\": 1,\n      \"quotaExceeded\": 0,\n      \"cacheHits\": 1\n    }\n  }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_bulk01" },
            { "key": "X-Quota-Limit", "value": "1000" },
            { "key": "X-Quota-Remaining", "value": "998" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "400 Bad Request — Invalid batch payload",
          "status": "Bad Request",
          "code": 400,
          "body": "{\n  \"error\": {\n    \"code\": \"invalid_bulk_request\",\n    \"message\": \"npis must be a non-empty array of up to 50 10-digit strings.\"\n  },\n  \"meta\": { \"requestId\": \"req_bulk400\" }\n}"
        }
      ]
    },
    {
      "name": "Provider search",
      "request": {
        "name": "Search providers (NPPES directory)",
        "description": "Directory-style search against the public NPPES Read API. Requires at least one of `last_name` or `organization_name` (state-only is rejected). Results are not cached in v1. Each HTTP 200 response — including an empty `data` array — consumes one monthly lookup credit for the entire page (same counter as single-NPI lookup). Pagination: `limit` (default 20, max 50), `skip` (max 1000); `meta.pagination.hasMore` uses an internal limit+1 probe.",
        "method": "GET",
        "url": {
          "raw": "{{baseUrl}}/api/v1/providers/search?last_name=Smith&limit=10",
          "host": ["{{baseUrl}}"],
          "path": ["api", "v1", "providers", "search"],
          "query": [
            { "key": "last_name", "value": "Smith", "description": "Required unless organization_name is set" },
            { "key": "organization_name", "value": "", "disabled": true, "description": "NPI-2 legal name; required unless last_name is set" },
            { "key": "first_name", "value": "", "disabled": true },
            { "key": "city", "value": "", "disabled": true },
            { "key": "state", "value": "", "disabled": true, "description": "2-letter USPS code; cannot be the only filter" },
            { "key": "postal_code", "value": "", "disabled": true },
            { "key": "taxonomy_description", "value": "", "disabled": true },
            { "key": "limit", "value": "10", "description": "1–50, default 20" },
            { "key": "skip", "value": "0", "disabled": true, "description": "0–1000 offset" }
          ]
        },
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{apiKey}}",
            "description": "Your API key (Bearer token)"
          }
        ]
      },
      "response": [
        {
          "name": "200 OK — Search results",
          "status": "OK",
          "code": 200,
          "body": "{\n  \"data\": [\n    {\n      \"npi\": \"1003000126\",\n      \"entityType\": \"NPI-1\",\n      \"status\": \"active\",\n      \"name\": {\n        \"full\": \"JOHN SMITH, M.D.\",\n        \"first\": \"JOHN\",\n        \"middle\": null,\n        \"last\": \"SMITH\",\n        \"prefix\": null,\n        \"credential\": \"M.D.\"\n      },\n      \"primaryTaxonomy\": {\n        \"code\": \"208M00000X\",\n        \"description\": \"Hospitalist\",\n        \"state\": \"DC\",\n        \"license\": \"MD600003480\"\n      },\n      \"taxonomies\": [],\n      \"mailingAddress\": {},\n      \"practiceLocations\": [],\n      \"enumerationDate\": \"2007-08-31\",\n      \"lastUpdated\": \"2026-05-01\",\n      \"source\": { \"name\": \"NPPES\", \"version\": \"2.1\" }\n    }\n  ],\n  \"meta\": {\n    \"requestId\": \"req_search01\",\n    \"pagination\": {\n      \"limit\": 10,\n      \"skip\": 0,\n      \"returned\": 1,\n      \"hasMore\": false\n    }\n  }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_search01" },
            { "key": "X-Quota-Limit", "value": "1000", "description": "Monthly lookup quota (one credit per successful search)" },
            { "key": "X-Quota-Remaining", "value": "999" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "400 Bad Request — Invalid search params",
          "status": "Bad Request",
          "code": 400,
          "body": "{\n  \"error\": {\n    \"code\": \"invalid_search_params\",\n    \"message\": \"At least one of last_name or organization_name is required.\"\n  },\n  \"meta\": { \"requestId\": \"req_search400\" }\n}"
        },
        {
          "name": "401 Unauthorized — Invalid API Key",
          "status": "Unauthorized",
          "code": 401,
          "body": "{\n  \"error\": {\n    \"code\": \"invalid_api_key\",\n    \"message\": \"Missing or invalid API key.\"\n  },\n  \"meta\": { \"requestId\": \"req_search401\" }\n}"
        },
        {
          "name": "403 Forbidden — Quota exceeded",
          "status": "Forbidden",
          "code": 403,
          "body": "{\n  \"error\": {\n    \"code\": \"quota_exceeded\",\n    \"message\": \"Monthly lookup quota has been exceeded.\"\n  },\n  \"meta\": { \"requestId\": \"req_search403q\" }\n}",
          "header": [
            { "key": "X-Quota-Limit", "value": "1000" },
            { "key": "X-Quota-Remaining", "value": "0" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "403 Forbidden — Subscription inactive",
          "status": "Forbidden",
          "code": 403,
          "body": "{\n  \"error\": {\n    \"code\": \"subscription_inactive\",\n    \"message\": \"Your subscription is not active.\"\n  },\n  \"meta\": { \"requestId\": \"req_search403s\" }\n}",
          "header": [
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "299" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "429 Too Many Requests — Rate limited",
          "status": "Too Many Requests",
          "code": 429,
          "body": "{\n  \"error\": {\n    \"code\": \"rate_limited\",\n    \"message\": \"Too many requests for this API key. Slow down and retry after the reset time.\"\n  },\n  \"meta\": { \"requestId\": \"req_search429\" }\n}",
          "header": [
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "0" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        },
        {
          "name": "502 Bad Gateway — Upstream unavailable",
          "status": "Bad Gateway",
          "code": 502,
          "body": "{\n  \"error\": {\n    \"code\": \"upstream_unavailable\",\n    \"message\": \"The upstream provider registry is temporarily unavailable.\"\n  },\n  \"meta\": { \"requestId\": \"req_search502\" }\n}",
          "header": [
            { "key": "X-Request-Id", "value": "req_search502" },
            { "key": "X-Quota-Limit", "value": "1000", "description": "Unchanged — this response does not consume quota" },
            { "key": "X-Quota-Remaining", "value": "1000" },
            { "key": "X-RateLimit-Limit", "value": "300" },
            { "key": "X-RateLimit-Remaining", "value": "298" },
            { "key": "X-RateLimit-Reset", "value": "1747800060" }
          ]
        }
      ]
    }
  ]
}