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://api.medfabric.com/api/v1/provider/1234567890"

Plan	Scopes	Rate Limit
Basic	`verify:single, verify:search`	100/month
Pro	`verify:single, verify:search, verify:batch, verify:export`	5,000/month
Enterprise	`all scopes`	Unlimited

Contact sales@medfabric.com for API key access.

Base URL

https://api.medfabric.com/api/v1

During beta, use http://localhost:3001/api/v1 for local development.

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://api.medfabric.com/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://api.medfabric.com/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

No auth required

/api/v1/status

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

Example Request

curl

curl "https://api.medfabric.com/api/v1/status"

Response (200)

JSON

{
  "ok": true,
  "data": {
    "status": "operational",
    "version": "1.0.0",
    "data": {
      "providers": { "count": 9034519, "source": "NPPES" },
      "licenses": { "count": 160982, "source": "CA Medical Board", "states": ["CA"] },
      "oig_exclusions": { "count": 82626, "source": "OIG LEIE", "note": "Currently excluded only" },
      "pecos_enrollments": { "count": 2957262, "source": "CMS PECOS" }
    },
    "queried_at": "2026-03-05T00:00: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://api.medfabric.com/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://api.medfabric.com/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://api.medfabric.com/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. Enterprise plan only.

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://api.medfabric.com/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 real-time notifications when compliance events are detected. Webhooks must use HTTPS. Enterprise plan only.

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://api.medfabric.com/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.

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

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

{
  "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://api.medfabric.com/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://api.medfabric.com/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.

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://api.medfabric.com/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://api.medfabric.com/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://api.medfabric.com/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,034,519

National provider identities, taxonomies, practice locations, enumeration dates. Source: CMS National Plan and Provider Enumeration System.

CA Medical Board

160,982

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

OIG LEIE

82,626

Federal exclusion and debarment records. Providers on this list are automatically flagged as non-compliant.

CMS PECOS

2,957,262

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 found for this provider
license_stale	License data older than 90 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, or state not covered

Rate Limits

Plan	Rate Limit	Batch Size
Basic	100 requests/month	N/A
Pro	5,000 requests/month	100 NPIs/request
Enterprise	Unlimited	100 NPIs/request

Exceeding rate limits returns 429 Too Many Requests. Contact us for enterprise rate limit adjustments.

Error Codes

Code	Meaning	Description
400	Bad Request	Invalid parameters (malformed NPI, missing required fields)
401	Unauthorized	Missing, invalid, or insufficient API key / scope
404	Not Found	Provider NPI not found in database
429	Too Many Requests	Rate limit exceeded
500	Server Error	Unexpected server failure

Questions? Contact api@medfabric.com

Back to MedFabric home