MedFabric API Documentation

REST API for healthcare provider verification and compliance data

Authentication

All API endpoints (except /api/v1/status) require a Bearer token in the Authorization header. Tokens are scoped — each key has access to specific endpoints based on its plan.

Header

Authorization: Bearer mf_your_api_key_here

Example curl

curl -H "Authorization: Bearer mf_your_api_key" \
  "https://medfabric.org/api/v1/provider/1234567890"

Plan	Scopes	Rate Limit
Basic	`verify:single`	50/month
Pro	`verify:single, verify:batch, verify:export, verify:changes`	1,000/month
Growth	`verify:single, verify:batch, verify:export, verify:changes`	5,000/month
Enterprise	`verify:single, verify:batch, verify:export, verify:changes, verify:audit`	25,000/month

Contact sales@medfabric.org for API key access.

Base URL

https://medfabric.org/api/v1

For local development, use http://localhost:3001/api/v1.

Response Format

All responses use a consistent JSON envelope:

// Success
{ "ok": true,  "timestamp": "2026-03-05T00:00:00.000Z", "data": { ... } }

// Error
{ "ok": false, "timestamp": "2026-03-05T00:00:00.000Z", "error": "message" }

// Paginated
{ "ok": true, "data": [...],
  "pagination": { "total": 100, "limit": 50, "offset": 0, "has_more": true } }

GET

Provider Lookup

/api/v1/provider/{npi}

Primary provider lookup. Returns a flat response combining all data layers: provider identity, license status, OIG exclusion screening, Medicare enrollment, compliance determination, and data quality score.

Auth

Bearer token required. Scope: verify:single

Path Parameters

Name	Type	Required	Description
npi	string	required	10-digit NPI number

Example Request

curl

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/provider/1234567890"

Response (200)

JSON

{
  "ok": true,
  "timestamp": "2026-03-05T00:00:00.000Z",
  "data": {
    "npi": "1234567890",
    "provider": {
      "name": "John Smith",
      "first_name": "John",
      "last_name": "Smith",
      "type": "individual",
      "status": "A",
      "enumeration_date": "2005-06-02",
      "location": { "city": "Los Angeles", "state": "CA", "postal_code": "90001" },
      "taxonomy": "207R00000X"
    },
    "license": {
      "license_number": "A12345",
      "license_type": "physician",
      "state": "CA",
      "authority": "ca_mbc",
      "status": "active",
      "expires_at": "2027-01-15",
      "last_checked_at": "2026-02-20T00:00:00.000Z",
      "match_method": "npi",
      "match_confidence": 1.0
    },
    "compliance": {
      "status": "compliant",
      "reasons": []
    },
    "oig_exclusion": {
      "excluded": false
    },
    "medicare_enrollment": {
      "enrolled": true,
      "enrollment_count": 1,
      "provider_type": "Physician - Internal Medicine",
      "state": "CA"
    },
    "data_quality_score": 0.92,
    "queried_at": "2026-03-05T00:00:00.000Z"
  }
}

Error Responses

401 — Invalid or missing API key
404 — NPI not found in provider database

GET

Provider Search

/api/v1/search

Name-based provider search. Returns matching providers with basic identity info and license indicators.

Query Parameters

Name	Type	Required	Description
last_name	string	required	Provider last name (min 2 characters)
first_name	string	optional	Provider first name
state	string	optional	2-letter state code
limit	number	optional	Results per page (default 20, max 50)

Example Request

curl

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/search?last_name=Smith&first_name=John&state=CA"

Response (200)

JSON

{
  "ok": true,
  "data": {
    "results": [
      {
        "npi": "1234567890",
        "name": "John Smith",
        "first_name": "JOHN",
        "last_name": "SMITH",
        "type": "individual",
        "state": "CA",
        "city": "Los Angeles",
        "taxonomy": "207R00000X",
        "has_ca_license": true
      }
    ],
    "count": 1,
    "limit": 20
  }
}

GET

System Status

/api/v1/status

System health and data freshness. Returns record counts for all data sources.

Auth

Bearer token required (any valid API key). For public, unauthenticated per-state counts and refresh dates, use /api/v1/coverage.

Example Request

curl

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/status"

Response (200)SAMPLE — static example, not live data

JSON — sample

// SAMPLE — static example, not live data.
// Counts as of Oct 3, 2026; current figures: GET /api/v1/coverage
{
  "ok": true,
  "data": {
    "status": "operational",
    "version": "1.0.0",
    "data": {
      "providers": { "count": 9331906, "source": "NPPES" },
      "licenses": { "count": 945256, "source": "State Medical Boards", "states": ["CA", "CO", "FL", "IL", "MI", "NJ", "NY", "PA", "TX", "WA"] },
      "oig_exclusions": { "count": 84085, "source": "OIG LEIE", "note": "Currently excluded only" },
      "pecos_enrollments": { "count": 3127995, "source": "CMS PECOS" }
    },
    "queried_at": "2026-10-03T00:56:00.000Z"
  }
}

GET

Single Verify

verify:single

/api/v1/verify

Verify a single NPI. Returns provider details, license info, OIG exclusion check, Medicare enrollment, compliance status, quality flags, and freshness metadata.

Query Parameters

Name	Type	Required	Description
npi	string	required	10-digit NPI number
state	string	optional	2-letter state code (defaults to provider's primary state)

Example Request

curl

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/verify?npi=1003000639&state=CA"

Response (200)

JSON

{
  "ok": true,
  "data": {
    "npi": "1003000639",
    "provider": {
      "first_name": "PEYMAN",
      "last_name": "BENHARASH",
      "entity_type": "individual",
      "state": "CA",
      "city": "LOS ANGELES",
      "specialty": "208600000X"
    },
    "verification_status": "verified_active",
    "compliance": "compliant",
    "reasons": ["License is active and current"],
    "license": {
      "license_number": "85379",
      "license_type": "physician",
      "state": "CA",
      "authority": "ca_mbc",
      "status": "active",
      "expiration_date": "2027-07-31",
      "match_method": "name_fuzzy",
      "match_confidence": 0.9
    },
    "quality_flags": [],
    "freshness": { "age_days": 5, "policy": "realtime_7d" },
    "oig_exclusion": { "excluded": false },
    "medicare_enrollment": { "enrolled": true, "enrollment_count": 1 },
    "data_quality_score": 0.85
  }
}

POST

Batch Verify

verify:batch

/api/v1/verify/batch

Verify up to 100 NPIs in a single request. Returns individual results plus an aggregated compliance summary.

Body Parameters

Name	Type	Required	Description
npis	string[]	required	Array of 10-digit NPIs (max 100)
include_details	boolean	optional	Include full details per result (default false)

Example Request

curl

curl -X POST -H "Authorization: Bearer mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis":["1003000639","1710187976"],"include_details":true}' \
  "https://medfabric.org/api/v1/verify/batch"

Response (200)

JSON

{
  "ok": true,
  "data": {
    "results": [ ... ],
    "summary": {
      "total": 2,
      "compliant": 1,
      "non_compliant": 1,
      "unknown": 0
    }
  }
}

POST

Export

verify:export

/api/v1/verify/export

Export verification results as a downloadable CSV or JSON file. Includes all fields: provider info, license, OIG, PECOS, quality score.

Parameters

Name	Type	Required	Description
npis	string[]	required	Array of 10-digit NPIs (max 100)
format	query	optional	csv (default) or json

Example Request

curl

curl -X POST -H "Authorization: Bearer mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"npis":["1003000639","1710187976"]}' \
  -o export.csv \
  "https://medfabric.org/api/v1/verify/export?format=csv"

GET

Changes Feed

verify:changes

/api/v1/changes

Paginated feed of compliance events detected during data ingestion. Includes license status changes, OIG exclusion additions/removals, and compliance status transitions. Pro plan and above.

Query Parameters

Name	Type	Required	Description
since	string	required	ISO 8601 timestamp — return events after this date
event_type	string	optional	Filter by event type (e.g. license_status_changed, oig_exclusion_added)
npi	string	optional	Filter events for a specific NPI
limit	number	optional	Results per page (default 50, max 500)
offset	number	optional	Pagination offset (default 0)

Example Request

curl

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/changes?since=2026-01-01&event_type=license_status_changed&limit=25"

Response (200)

JSON

{
  "ok": true,
  "data": [
    {
      "id": "evt_a1b2c3d4",
      "event_type": "license_status_changed",
      "npi": "1234567890",
      "provider_name": "John Smith",
      "old_value": "active",
      "new_value": "inactive",
      "detected_at": "2026-03-01T02:15:00.000Z",
      "source": "ca_mbc"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

Event Types

Type	Description
oig_exclusion_added	Provider added to OIG LEIE exclusion list
oig_exclusion_removed	Provider removed from OIG LEIE exclusion list
license_status_changed	License status changed (e.g. active to inactive)
license_expired	License expiration detected
compliance_status_changed	Overall compliance determination changed

POST

Webhooks

verify:changes

/api/v1/webhooks

Register webhooks to receive notifications when compliance events are detected. Webhooks must use HTTPS. Enterprise plan only.

Events fire for providers on your roster when the daily monitoring sweep detects a change: exclusions added or removed (OIG, SAM.gov, state Medicaid), licence status changes and expirations, licences expiring within 30 days, NPI deactivation, and compliant/non-compliant transitions. Registration returns a secret once — store it. Every delivery is signed: X-MedFabric-Signature: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Compare in constant time and reject old timestamps. Ten consecutive failed deliveries disable the subscription.

Endpoints

Method	Path	Description
POST	/api/v1/webhooks	Register a new webhook
GET	/api/v1/webhooks	List your registered webhooks
DELETE	/api/v1/webhooks/{id}	Delete a webhook

Register Webhook — Body Parameters

Name	Type	Required	Description
url	string	required	HTTPS URL to receive webhook events
event_types	string[]	required	Array of event types to subscribe to

Example — Register Webhook

curl

curl -X POST -H "Authorization: Bearer mf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/medfabric","event_types":["oig_exclusion_added","license_status_changed"]}' \
  "https://medfabric.org/api/v1/webhooks"

Response (201)

JSON

{
  "ok": true,
  "data": {
    "id": "wh_a1b2c3d4e5f67890",
    "url": "https://example.com/webhooks/medfabric",
    "event_types": ["oig_exclusion_added", "license_status_changed"],
    "created_at": "2026-03-04T12:00:00.000Z"
  }
}

Webhook Payload

Each webhook delivery POSTs a JSON payload to your URL:

Webhook Payload

{
  "event_id": "evt_a1b2c3d4",
  "event_type": "license_status_changed",
  "npi": "1234567890",
  "provider_name": "John Smith",
  "old_value": "active",
  "new_value": "revoked",
  "detected_at": "2026-03-04T02:15:00.000Z",
  "source": "ca_mbc"
}

Supply Analytics

Pre-computed analytics on provider supply by taxonomy (specialty), geography, and historical trends. Growth plan and above.

GET /api/v1/analytics/supply

Returns a supply summary or taxonomy-level metrics. Use view=summary (default) for high-level counts or view=taxonomy for per-specialty breakdowns.

Name	Type	Required	Description
view	string	optional	summary (default) or taxonomy
sort_by	string	optional	total_count, active_count, or state_count (taxonomy view)
order	string	optional	desc (default) or asc
limit	integer	optional	Max results (default 50, max 200)
offset	integer	optional	Pagination offset

Example — Summary (sample)

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/analytics/supply"

// SAMPLE — static example, not live data. Current provider counts: GET /api/v1/coverage
{
  "ok": true,
  "data": {
    "total_providers": 9034519,
    "active_providers": 8901234,
    "total_taxonomies": 872,
    "states_covered": 56,
    "last_computed": "2026-03-04T00:00:00.000Z"
  }
}

GET /api/v1/analytics/geo

Geographic distribution of providers. Without filters, returns state-level summaries. Add state to drill down into cities.

Name	Type	Required	Description
state	string	optional	Two-letter state code (e.g., CA)
city	string	optional	City name (requires state)
limit	integer	optional	Max results (default 50, max 200)
offset	integer	optional	Pagination offset

Example

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/analytics/geo?state=CA"

{
  "ok": true,
  "data": [
    {
      "state": "CA",
      "city": "Los Angeles",
      "provider_count": 85000,
      "active_count": 82000,
      "top_taxonomies": [{"code": "207Q00000X", "count": 12000}]
    }
  ],
  "pagination": { "total": 482, "limit": 50, "offset": 0, "has_more": true }
}

GET /api/v1/analytics/trends

Historical supply snapshots for trend analysis. Tracks provider counts over time by dimension.

Name	Type	Required	Description
dimension_type	string	optional	overall (default), taxonomy, or state
dimension_value	string	optional	Dimension value (default: total)
limit	integer	optional	Max data points (default 90, max 365)

Example

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/analytics/trends?dimension_type=state&dimension_value=CA"

{
  "ok": true,
  "data": {
    "dimension_type": "state",
    "dimension_value": "CA",
    "data_points": [
      { "snapshot_date": "2026-03-04", "provider_count": 450000, "active_count": 430000 },
      { "snapshot_date": "2026-03-03", "provider_count": 449800, "active_count": 429900 }
    ]
  }
}

Provider Network

Query provider affiliations, practice locations, and organizational relationships derived from NPPES data. Growth plan and above.

GET /api/v1/network/{npi}

Returns a provider's complete network: affiliations (as source and target), practice locations, and co-located providers at each location.

Name	Type	Required	Description
npi	string	required	10-digit NPI (path parameter)

Example

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/network/1003000639"

{
  "ok": true,
  "data": {
    "provider": { "npi": "1003000639", "name": "John Smith", "provider_type": "individual" },
    "affiliations": [
      {
        "relationship_type": "authorized_official",
        "related_npi": "1234567890",
        "related_name": "Acme Health",
        "confidence_score": 1.0,
        "direction": "outgoing"
      }
    ],
    "locations": [
      {
        "address_line1": "123 Medical Ct",
        "city": "Los Angeles",
        "state": "CA",
        "provider_count": 12,
        "co_located_providers": [{ "npi": "...", "name": "...", "provider_type": "organization" }]
      }
    ],
    "network_summary": { "total_affiliations": 3, "by_type": { "authorized_official": 1, "co_located": 2 }, "total_locations": 1 }
  }
}

GET /api/v1/network/org/{npi}

Returns an organization's members. Queries provider affiliations where the organization is the target.

Name	Type	Required	Description
npi	string	required	Organization 10-digit NPI (path parameter)
limit	integer	optional	Max results (default 100, max 200)
taxonomy_code	string	optional	Filter members by primary taxonomy code

Example

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/network/org/1234567890?limit=50"

{
  "ok": true,
  "data": {
    "organization": { "npi": "1234567890", "name": "Acme Health", "provider_type": "organization" },
    "members": [
      { "npi": "1003000639", "name": "John Smith", "relationship_type": "authorized_official", "confidence_score": 1.0 }
    ],
    "statistics": { "total_members": 42, "returned": 42, "by_relationship_type": { "authorized_official": 1, "co_located": 35, "same_org_name": 6 } }
  }
}

GET /api/v1/network/clusters

Returns practice location clusters for a state. Each cluster includes sample providers.

Name	Type	Required	Description
state	string	required	Two-letter state code (e.g., CA)
city	string	optional	Filter by city name
min_providers	integer	optional	Minimum providers per cluster (default 5)
limit	integer	optional	Max clusters returned (default 50, max 200)

Example

curl -H "Authorization: Bearer mf_your_key" \
  "https://medfabric.org/api/v1/network/clusters?state=CA&min_providers=10"

{
  "ok": true,
  "data": {
    "clusters": [
      {
        "id": "loc_abc123",
        "address_line1": "123 Medical Center Dr",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90012",
        "provider_count": 45,
        "org_count": 3,
        "sample_providers": [
          { "npi": "1003000639", "name": "John Smith", "provider_type": "individual" }
        ]
      }
    ]
  }
}

Data Model

MedFabric aggregates four authoritative data sources into a unified provider profile:

NPPES

9,346,307

National provider identities (individuals and organizations with an NPI), taxonomies, practice locations, enumeration dates. Source: CMS National Plan and Provider Enumeration System.

State licensing boards (9 states)

1,216,112

Medical license records (681,678 active; the rest inactive, expired, or revoked): status, expiration dates, disciplinary actions, license type. Linked to NPPES by NPI and name matching.

OIG LEIE

84,005

Active federal exclusion records. Providers on this list are automatically flagged as non-compliant.

CMS PECOS

3,128,618

Medicare Fee-for-Service enrollment records. Provider type, enrollment state, specialty classification.

As of Oct 28, 2026 · per-state counts and refresh dates

NPPES

—

National provider identities (individuals and organizations with an NPI), taxonomies, practice locations, enumeration dates. Source: CMS National Plan and Provider Enumeration System.

State licensing boards

—

Medical license records: status, expiration dates, disciplinary actions, license type. Linked to NPPES by NPI and name matching.

OIG LEIE

—

Active federal exclusion records. Providers on this list are automatically flagged as non-compliant.

CMS PECOS

—

Medicare Fee-for-Service enrollment records. Provider type, enrollment state, specialty classification.

Quality & Compliance

Data Quality Score

Every response includes a data_quality_score from 0 to 1. This composite score reflects how much data we have for the provider:

Component	Weight	Criteria
NPI identity	20%	Valid NPI in NPPES
Name completeness	10%	First and last name present
License found	25%	CA license linked to provider
Match confidence	15%	License match confidence (NPI=1.0, name=0.9)
Medicare enrollment	15%	Found in CMS PECOS
OIG screening	15%	OIG check performed (always true)

Quality Flags

Explicit quality signals attached to each record:

Flag	Meaning
license_unmatched	No license in the state could be matched to this NPI. Not evidence that none exists — check the state board
source_not_checked	The state's records aren't yet matched to provider NPIs, so the licence (or NY conduct) check wasn't performed. Returned with `verification_status: "not_checked"`. Never read this as “no record”
license_stale	License data older than 60 days
license_revoked	License has been revoked
license_expiring_soon	License expires within 90 days
ambiguous_name_match	License matched by name with low confidence
oig_excluded	Provider is on OIG LEIE exclusion list
not_medicare_enrolled	Not found in CMS PECOS enrollment

Compliance Status

Compliance is determined by this priority chain:

compliant

Active license, no exclusions

non_compliant

OIG excluded, revoked, expired, inactive, or probation

unknown

NPI not found, no license, state not covered, or state records not checked

Rate Limits

Plan	Lookups / month	Requests / minute	Batch size
Basic	50	10	N/A
Pro	1,000	60	100 NPIs/request
Growth	5,000	120	100 NPIs/request
Enterprise	25,000 (soft — hard stop at 50,000)	300	100 NPIs/request

One lookup = one NPI verified. A batch or export of 100 NPIs uses 100 lookups; listing or editing your roster uses none. Dashboard and API lookups share the same allowance.
Over the monthly allowance you get 429 Too Many Requests with Retry-After; allowances reset at the start of each calendar month (UTC). A batch that would go over is rejected whole, and the error says how many lookups remain.
Over the per-minute limit you get a 429 with Retry-After: 60.
Enterprise is a soft limit: we email you at 80% and 100%, keep serving past 100% (logged as overage), and stop at 2× the allowance. Contact us to raise it.

Error Codes

Code	Meaning	Description
400	Bad Request	Invalid parameters (malformed NPI, missing required fields)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key, but its scope or plan doesn't include this endpoint
404	Not Found	Provider NPI not found in database
429	Too Many Requests	Monthly lookup limit reached — see `Retry-After` (seconds) and `X-RateLimit-Reset`
500	Server Error	Unexpected server failure

Questions? Contact api@medfabric.org

Back to MedFabric home