NPIxray API

Medicare billing intelligence for developers

Access data on 1.2M+ Medicare providers. Revenue Scores, billing code breakdowns, specialty benchmarks, and market intelligence — all from CMS public data.

Base URL

npixray.com/api/v1

Free Tier

100 req/day, no key

Pro Tier

10K req/day, API key

Auth

X-API-Key header

API Playground

Try the API live — enter an NPI number and see the response.

GET/api/v1/provider/1306849450

// Click Run to make an API request

Authentication

Free tier endpoints require no authentication. For Pro endpoints, include your API key in the request header:

http
GET /api/v1/provider/1234567890/full
Host: npixray.com
X-API-Key: npx_your_api_key_here

# Or use the Authorization header:
Authorization: Bearer npx_your_api_key_here

Free Tier

100 requests per day per IP
Provider lookup + Revenue Score
Provider search
Specialty benchmarks
State aggregate stats

Pro Tier — $49/mo

10,000 requests per day
Full billing breakdowns
All billing codes per provider
Multi-provider comparison
Batch lookup (100 NPIs)
Group practice scan (50 NPIs)
Market intelligence
Score distributions

Get API Key — $49/mo

Free Endpoints

GET/api/v1/provider/{npi}

Get basic provider info including name, specialty, location, Medicare payment totals, and Revenue Score.

npi(path, required) 10-digit NPI number

curl https://npixray.com/api/v1/provider/1306849450

{
  "data": {
    "npi": "1306849450",
    "name": "JAMES MARTINEZ",
    "credential": "MD",
    "specialty": "Urology",
    "state": "FL",
    "city": "MIAMI",
    "total_medicare_payment": 245832.50,
    "total_beneficiaries": 542,
    "total_services": 3210,
    "revenue_score": 42
  }
}

GET/api/v1/search

Search for providers by name, state, and/or specialty. Returns up to 50 results sorted by Medicare payment.

name(query) Provider name (first, last, or full)

state(query) Two-letter state abbreviation

specialty(query) Specialty name

limit(query) Results limit (max 50, default 20)

curl "https://npixray.com/api/v1/search?name=Smith&state=FL&limit=5"

{
  "data": [
    {
      "npi": "1234567890",
      "name": "JOHN SMITH",
      "specialty": "Internal Medicine",
      "state": "FL",
      "city": "MIAMI",
      "revenue_score": 58,
      ...
    }
  ],
  "total": 5
}

GET/api/v1/benchmarks/{specialty?}

Get specialty benchmark data including E&M coding rates, care management adoption, and average payments. Omit specialty for all benchmarks.

specialty(path, optional) Specialty slug (e.g. 'internal-medicine') or exact name

curl https://npixray.com/api/v1/benchmarks/internal-medicine

{
  "data": {
    "specialty": "Internal Medicine",
    "provider_count": 88703,
    "avg_medicare_patients": 169,
    "avg_total_payment": 77297,
    "pct_99214": 0.6073,
    "ccm_adoption_rate": 0.045,
    "awv_adoption_rate": 0.3536,
    ...
  }
}

GET/api/v1/stats/{state?}

Get aggregate Medicare statistics for a state, including top specialties and cities. Omit state for all states.

state(path, optional) Two-letter state abbreviation

curl https://npixray.com/api/v1/stats/FL

{
  "data": {
    "state": "FL",
    "name": "Florida",
    "total_providers": 42150,
    "total_payment": 5892431000,
    "avg_payment": 139810,
    "top_specialties": [...],
    "top_cities": [...]
  }
}

Pro Endpoints

Require a Pro API key ($49/mo). Get your key

GET/api/v1/provider/{npi}/fullPro

Complete billing breakdown including E&M distribution, all care management codes, estimated missed revenue, and specialty benchmark comparison.

npi(path, required) 10-digit NPI number

curl -H "X-API-Key: npx_your_key" \
  https://npixray.com/api/v1/provider/1306849450/full

{
  "data": {
    "npi": "1306849450",
    "name": "JAMES MARTINEZ",
    "revenue_score": 42,
    "em_distribution": {
      "em_99213": 1200, "em_99214": 890, "em_99215": 120, ...
    },
    "care_management": {
      "ccm_99490_services": 0, "rpm_99454_services": 0, ...
    },
    "estimated_missed_revenue": 563230,
    "benchmark": { ... }
  }
}

GET/api/v1/provider/{npi}/codesPro

All HCPCS/CPT codes billed by a provider with service counts and payment amounts.

npi(path, required) 10-digit NPI number

limit(query) Max results (default 50, max 200)

curl -H "X-API-Key: npx_your_key" \
  https://npixray.com/api/v1/provider/1306849450/codes

{
  "data": {
    "npi": "1306849450",
    "name": "JAMES MARTINEZ",
    "codes": [
      { "hcpcs_code": "99214", "services": 890, "payment": 115752 },
      { "hcpcs_code": "99213", "services": 1200, "payment": 110400 },
      ...
    ]
  }
}

GET/api/v1/comparePro

Compare 2-10 providers side by side with full billing breakdowns and Revenue Scores.

npis(query, required) Comma-separated NPI numbers (2-10)

curl -H "X-API-Key: npx_your_key" \
  "https://npixray.com/api/v1/compare?npis=1306849450,1234567890"

{
  "data": [
    { "npi": "1306849450", "revenue_score": 42, ... },
    { "npi": "1234567890", "revenue_score": 67, ... }
  ]
}

GET/api/v1/market/{state}/{city?}/{specialty?}Pro

Market intelligence for a geographic + specialty segment. Includes adoption rates, E&M distribution, missed revenue estimates, and top providers.

state(path, required) Two-letter state code

city(path, optional) City name

specialty(path, optional) Specialty name

curl -H "X-API-Key: npx_your_key" \
  "https://npixray.com/api/v1/market/FL/Miami/Internal%20Medicine"

{
  "data": {
    "market": { "state": "FL", "city": "Miami", "specialty": "Internal Medicine" },
    "summary": {
      "providers": 342, "estimated_missed_revenue": 48200000,
      "capture_rate": 58
    },
    "adoption_rates": { "ccm": 4, "rpm": 2, "bhi": 0, "awv": 35 },
    "top_providers": [...]
  }
}

GET/api/v1/scores/{state}/{specialty?}Pro

Revenue Score distribution across providers. See how scores are spread for any state/specialty segment.

state(path, required) Two-letter state code

specialty(path, optional) Specialty name

curl -H "X-API-Key: npx_your_key" \
  "https://npixray.com/api/v1/scores/FL/Internal%20Medicine"

{
  "data": {
    "state": "FL",
    "specialty": "Internal Medicine",
    "distribution": [
      { "bucket": "0-20", "count": 45 },
      { "bucket": "21-40", "count": 128 },
      { "bucket": "41-60", "count": 201 },
      { "bucket": "61-80", "count": 89 },
      { "bucket": "81-100", "count": 23 }
    ],
    "total": 486
  }
}

POST/api/v1/providers/batchPro

Look up multiple providers in a single request. Returns basic provider info and Revenue Scores for up to 100 NPIs at once.

npis(body, required) Array of 10-digit NPI strings (1-100)

curl -X POST -H "X-API-Key: npx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis": ["1306849450", "1234567890"]}' \
  https://npixray.com/api/v1/providers/batch

{
  "data": {
    "providers": [
      { "npi": "1306849450", "name": "JAMES MARTINEZ", "revenue_score": 42, ... },
      { "npi": "1234567890", "name": "JOHN SMITH", "revenue_score": 67, ... }
    ],
    "found": 2, "requested": 2
  }
}

POST/api/v1/group-scanPro

Run a full practice-level revenue scan across 2-50 providers. Returns aggregated missed revenue, program adoption rates, E&M distribution, and a prioritized action plan.

npis(body, required) Array of 10-digit NPI strings (2-50)

practiceName(body, optional) Practice name for the report

curl -X POST -H "X-API-Key: npx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis": ["1306849450", "1234567890"], "practiceName": "Metro Health"}' \
  https://npixray.com/api/v1/group-scan

{
  "data": {
    "practiceName": "Metro Health",
    "totalProviders": 2,
    "totalMissedRevenue": 892430,
    "averageRevenueScore": 54,
    "programAdoption": { "ccm": {...}, "rpm": {...} },
    "providers": [...],
    "practiceActionPlan": [...]
  }
}

FHIR & EHR Integration

Integrate NPIxray into your EHR, practice management system, or clinical workflow.

GET/api/v1/fhir?npi={npi}

FHIR R4-compatible Practitioner resource with NPIxray Revenue Score extensions. Returns standard FHIR identifiers, qualifications, and address fields plus custom extensions for billing intelligence.

npi(query, required) 10-digit NPI number

curl https://npixray.com/api/v1/fhir?npi=1306849450

{
  "resourceType": "Practitioner",
  "id": "1306849450",
  "identifier": [{ "system": "http://hl7.org/fhir/sid/us-npi", "value": "1306849450" }],
  "name": [{ "family": "MARTINEZ", "given": ["JAMES"], "suffix": ["MD"] }],
  "extension": [
    { "url": ".../revenue-score", "valueInteger": 42 },
    { "url": ".../total-medicare-payment", "valueDecimal": 245832.50 }
  ]
}

Embeddable Widget

Drop an NPIxray Revenue Score card into any web application. Two integration options:

Option 1: Script Tag (recommended)

html
<!-- Add to your page -->
<div data-npixray-npi="1306849450"></div>
<script src="https://npixray.com/embed.js"></script>

<!-- Optional: customize dimensions -->
<div data-npixray-npi="1306849450"
     data-width="400px"
     data-height="350px"></div>
<script src="https://npixray.com/embed.js"></script>

Option 2: Direct Iframe

html
<iframe
  src="https://npixray.com/embed/1306849450"
  width="340" height="320"
  frameborder="0"
  style="border-radius: 12px"
  title="NPIxray Revenue Score">
</iframe>

EHR Vendor Integration

FHIR R4 Practitioner resource for CDS Hooks / SMART on FHIR
Iframe widget for embedded dashboards within EHR chrome
Custom extensions under npixray.com/fhir/extension/
No PHI transmitted — uses public CMS data only

OpenAPI Specification

Import our full API spec into Postman, Swagger UI, or any OpenAPI-compatible tool.

bash
# Download the OpenAPI 3.0 spec
curl https://npixray.com/api/v1/openapi

# Import into Postman, Swagger Editor, or use with code generators:
# openapi-generator generate -i https://npixray.com/api/v1/openapi -g python

View OpenAPI Spec (JSON)

Code Examples

Python

python
import requests

# Free tier — no key needed
response = requests.get("https://npixray.com/api/v1/provider/1306849450")
provider = response.json()["data"]
print(f"{provider['name']} — Revenue Score: {provider['revenue_score']}")

# Pro tier — with API key
headers = {"X-API-Key": "npx_your_api_key"}
response = requests.get(
    "https://npixray.com/api/v1/provider/1306849450/full",
    headers=headers
)
full = response.json()["data"]
print("Missed Revenue:", locale.currency(full['estimated_missed_revenue'], grouping=True))

JavaScript / Node.js

javascript
// Free tier
const res = await fetch("https://npixray.com/api/v1/provider/1306849450");
const { data } = await res.json();
console.log(`${data.name} — Score: ${data.revenue_score}`);

// Pro tier
const proRes = await fetch("https://npixray.com/api/v1/provider/1306849450/full", {
  headers: { "X-API-Key": "npx_your_api_key" }
});
const { data: full } = await proRes.json();
console.log(`Missed: $${full.estimated_missed_revenue.toLocaleString()}`);

R

r
library(httr)
library(jsonlite)

# Free tier
res <- GET("https://npixray.com/api/v1/provider/1306849450")
data <- content(res, as = "parsed")$data
cat(sprintf("%s — Revenue Score: %d\n", data$name, data$revenue_score))

# Search for providers
res <- GET("https://npixray.com/api/v1/search",
           query = list(name = "Smith", state = "FL"))
providers <- content(res, as = "parsed")$data

cURL

bash
# Provider lookup
curl https://npixray.com/api/v1/provider/1306849450

# Search
curl "https://npixray.com/api/v1/search?name=Smith&state=FL"

# Benchmarks
curl https://npixray.com/api/v1/benchmarks/internal-medicine

# Pro endpoint (with API key)
curl -H "X-API-Key: npx_your_key" \
  https://npixray.com/api/v1/provider/1306849450/full

Rate Limits & Headers

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-02-18T00:00:00.000Z

Tier	Daily Limit	Auth	Endpoints
Anonymous	100	None (IP-based)	Free endpoints only
Free Key	100	API Key	Free endpoints only
Pro Key	10,000	API Key	All endpoints

Data Source

All data is sourced from the CMS Medicare Physician & Other Practitioners dataset, a free public dataset published by the Centers for Medicare & Medicaid Services. Data covers Medicare Part B fee-for-service claims and includes provider demographics, service utilization, and payment information.

Start Building