Documentation

Single-page reference for MVP. The machine-readable contract lives in docs/openapi.yaml in the repository.

Quick start

1. Sign in and create an API key from the dashboard (when enabled).
2. Copy the raw key once; store it securely.
3. Call GET /api/v1/npi/{npi} with header Authorization: Bearer YOUR_API_KEY.

Authentication

All lookup requests use bearer API key authentication. Keys are issued from your account; rate limiting is post-MVP—monthly quota per plan still applies.

Endpoint

GET https://api.npi-api.com/api/v1/npi/{npi} (production) or GET http://localhost:3000/api/v1/npi/{npi} (local, when the route is wired).

Path parameter npi must be exactly 10 digits (leading or trailing whitespace is trimmed; invalid input returns 400 with code invalid_npi).

Examples

cURL

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.npi-api.com/api/v1/npi/1003000126"

JavaScript (fetch)

const res = await fetch("https://api.npi-api.com/api/v1/npi/1003000126", {
  headers: { Authorization: `Bearer ${process.env.NPI_API_KEY}` },
});
const body = await res.json();

Python (httpx)

import os, httpx

r = httpx.get(
    "https://api.npi-api.com/api/v1/npi/1003000126",
    headers={"Authorization": f"Bearer {os.environ['NPI_API_KEY']}"},
)
r.raise_for_status()
print(r.json())

Sample success response

See OpenAPI schema NpiLookupResponse: top-level data (provider) and meta.requestId; optional meta.cached.

Sample error responses

• 400 — invalid_npi
• 401 — invalid_api_key
• 403 — subscription_inactive or quota_exceeded
• 404 — npi_not_found
• 500 — internal_error
• 502 — upstream_unavailable

Quota

Monthly lookup quotas and key limits depend on your plan. Overage billing and transactional email alerts are out of scope for MVP; see pricing for included quota.

Pricing →