One API. Five federal sources. Cryptographically signed responses.

Getting started

Resolve a US healthcare provider against the federal record in a single request. The sample key pk_dx_sample is live — it works against every read endpoint at 100 requests/hour, no signup required. Swap it for your own key when you move past the sandbox.

The base URL is https://api.fonteum.com/v1. Authentication is one header. Responses are JSON, and every field carries provenance.

curl https://api.fonteum.com/v1/npi/1234567890 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "npi": "1234567890",
  "entity_type": "organization",
  "organization_name": "Mercy General Hospital",
  "primary_taxonomy": "General Acute Care Hospital",
  "address": { "city": "Sacramento", "state": "CA", "postal_code": "95819" },
  "_source": "NPPES",
  "_snapshot": "2026-05-01",
  "_confidence": 0.98
}

That single record is assembled from NPPES, OIG LEIE, CMS PECOS, CMS Care Compare, and CMS Open Payments. The next sections cover authentication, each resolver, and the provenance contract that backs every value.

Authentication

Pass your key in the X-Fonteum-Key header on every request. There are no OAuth dances and no bearer-token exchange for read endpoints — the key is the credential. Keep production keys server-side; the sample key is safe to ship in client examples because it is read-only and rate-limited.

curl https://api.fonteum.com/v1/npi/1234567890 \
  -H "X-Fonteum-Key: pk_dx_sample"

A missing or unknown key returns 401; exceeding your hourly budget returns 429 with a Retry-After header.

{
  "error": {
    "code": "invalid_key",
    "message": "The X-Fonteum-Key header is missing or not recognized.",
    "request_id": "req_8Fk2pQ"
  }
}

Plan tiers

Rate-limit headers ride on every response — see Rate limits.

Resolve a provider by NPI

The NPI resolver is the front door. Hand it a 10-digit National Provider Identifier and it returns the cleaned NPPES record joined to every other federal source we hold for that provider — enrollment, sanctions, quality, and payments — each value tagged with where it came from.

curl https://api.fonteum.com/v1/npi/1234567890 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "npi": "1234567890",
  "entity_type": "organization",
  "organization_name": "Mercy General Hospital",
  "primary_taxonomy": "General Acute Care Hospital",
  "enumeration_date": "2007-05-23",
  "address": { "city": "Sacramento", "state": "CA", "postal_code": "95819" },
  "pecos_enrolled": true,
  "_source": "NPPES",
  "_dataset_id": "nppes",
  "_snapshot": "2026-05-01",
  "_confidence": 0.98
}

A 10-digit NPI that does not exist returns 404 not_found. Malformed identifiers (wrong length, non-numeric) return 400 invalid_npi before any lookup runs.

Resolve a hospital by CCN

Facilities are keyed by CMS Certification Number (CCN), not NPI. The CCN resolver returns the facility identity from the CMS Provider of Services file joined to its Care Compare quality record and ownership lineage.

curl https://api.fonteum.com/v1/ccn/050441 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "ccn": "050441",
  "facility_name": "Mercy General Hospital",
  "facility_type": "Acute Care Hospital",
  "ownership_type": "Voluntary non-profit - Private",
  "address": { "city": "Sacramento", "state": "CA" },
  "overall_star": 4,
  "_source": "CMS POS",
  "_dataset_id": "cms_pos_facilities",
  "_snapshot": "2026-04-15",
  "_confidence": 1.0
}

CCNs are 6 characters; the leading two digits encode the state. An unknown CCN returns 404 not_found.

Search providers

When you do not yet have an identifier, search by name, taxonomy, and location. Search returns a ranked list of candidate NPIs; resolve the one you want for the full record. Results are paginated and capped at 100 per page.

curl "https://api.fonteum.com/v1/search?q=cardiology&state=CA&limit=10" \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "query": { "q": "cardiology", "state": "CA", "limit": 10 },
  "total": 1843,
  "results": [
    {
      "npi": "1234567890",
      "name": "Mercy Cardiology Associates",
      "taxonomy": "Cardiovascular Disease",
      "city": "Sacramento",
      "_match_score": 0.91
    }
  ]
}

_match_score is the entity-resolution confidence for the query, not the provenance confidence of the underlying record. Use state and taxonomy to narrow before paging.

Cross-dataset facts

A provider record is more than its NPPES row. Ask for include=facts and the resolver returns every cross-dataset fact we can attach to that NPI — an OIG LEIE exclusion, a PECOS enrollment status, a Care Compare star — each as its own object with its own provenance. Facts are never merged into a single flattened field; you always see which source asserted what.

curl "https://api.fonteum.com/v1/npi/1234567890?include=facts" \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "npi": "1234567890",
  "facts": [
    {
      "type": "exclusion",
      "value": false,
      "_source": "OIG LEIE",
      "_dataset_id": "oig_leie_exclusions",
      "_snapshot": "2026-05-01",
      "_confidence": 1.0
    },
    {
      "type": "pecos_enrolled",
      "value": true,
      "_source": "CMS PECOS",
      "_dataset_id": "cms_pecos_ppef",
      "_snapshot": "2026-04-20",
      "_confidence": 0.97
    }
  ]
}

An exclusion fact with value: true means the provider appears on the OIG List of Excluded Individuals/Entities as of _snapshot. Treat the absence of a fact as unknown, not as a negative finding.

Quality scores

CMS Care Compare publishes star ratings and measure-level scores for several facility types. The quality endpoint returns them keyed by facility type and identifier, with the measurement period and the source snapshot attached so you can cite the exact vintage.

Supported {type} values: hospital, nursing-home, home-health, hospice, dialysis, asc. The {id} is the facility CCN.

curl https://api.fonteum.com/v1/quality/hospital/050441 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "type": "hospital",
  "ccn": "050441",
  "overall_star": 4,
  "measurement_period": "2024-07-01/2025-06-30",
  "measures": [
    { "id": "MORT_30_AMI", "value": 12.8, "national_avg": 12.9 },
    { "id": "READM_30_HOSP_WIDE", "value": 14.1, "national_avg": 15.3 }
  ],
  "_source": "CMS Care Compare",
  "_dataset_id": "cms_care_compare_hospital",
  "_snapshot": "2026-04-15",
  "_confidence": 1.0
}

CMS suppresses small-sample measures; suppressed values come back as null, never as zero.

Open Payments

CMS Open Payments discloses industry transfers of value to physicians and teaching hospitals. The payments endpoint returns the aggregated total for an NPI plus the underlying records, each linked to its disclosing manufacturer and program year.

curl https://api.fonteum.com/v1/payments/1234567890 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "npi": "1234567890",
  "program_year": 2024,
  "total_amount_usd": 18420.55,
  "record_count": 37,
  "records": [
    {
      "manufacturer": "Acme Devices Inc.",
      "amount_usd": 2500.0,
      "nature": "Consulting Fee",
      "date": "2024-09-12"
    }
  ],
  "_source": "CMS Open Payments",
  "_dataset_id": "cms_open_payments",
  "_snapshot": "2026-03-30",
  "_confidence": 0.95
}

Open Payments matches on name and address, not NPI, so _confidence reflects the strength of that match. Records below the CMS de-minimis threshold are excluded by the publisher.

Batch resolution

Resolving a panel of providers one request at a time is slow and burns your rate budget. The batch endpoint takes up to 1,000 NPIs in a single POST and returns each resolved record in array order. Unresolvable NPIs come back as null entries, not errors, so one bad identifier never fails the whole batch.

curl https://api.fonteum.com/v1/batch/npi \
  -H "X-Fonteum-Key: pk_dx_sample" \
  -H "Content-Type: application/json" \
  -d '{"npis":["1234567890","1987654321","1659876543"]}'

{
  "requested": 3,
  "resolved": 2,
  "results": [
    { "npi": "1234567890", "organization_name": "Mercy General Hospital", "_confidence": 0.98 },
    null,
    { "npi": "1659876543", "organization_name": "Sutter Health Group", "_confidence": 0.94 }
  ]
}

A batch counts as one request against your per-hour budget but is metered separately on a per-NPI ceiling. Batches larger than 1,000 NPIs return 400 batch_too_large.

Webhooks

Federal sources refresh on their own cadence — monthly for OIG LEIE, quarterly for the CMS POS file, annually for Open Payments. Rather than poll, subscribe to a webhook and we POST to your endpoint when a snapshot you depend on changes. Delivery URLs live on webhooks.fonteum.com.

Every delivery carries an X-Fonteum-Signature header of the form t=<timestamp>,v1=<hmac-sha256>. Recompute the HMAC over the raw body with your signing secret and compare in constant time before trusting the payload.

# Example delivery body POSTed to your endpoint:

{
  "event": "source.refreshed",
  "dataset_id": "oig_leie_exclusions",
  "snapshot": "2026-06-01",
  "previous_snapshot": "2026-05-01",
  "delivered_at": "2026-06-01T09:00:00Z"
}

Events

We retry non-2xx deliveries with exponential backoff for 24 hours.

Errors

Every error returns the same envelope: an error object with a stable machine code, a human message, and a request_id you can quote in support. HTTP status follows convention — 4xx is your request, 5xx is ours.

curl -i https://api.fonteum.com/v1/npi/0000000000 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "error": {
    "code": "not_found",
    "message": "No provider exists for NPI 0000000000.",
    "request_id": "req_8Fk2pQ"
  }
}

Codes

Retry only on 429, 500, and 503. Treat 4xx codes other than 429 as terminal — retrying will not change the outcome.

Provenance contract

Every value Fonteum returns is bound to a 14-tuple that says where it came from, when, under what license, and how sure we are. The keys are prefixed with an underscore so they never collide with source field names, and they appear on records, facts, and batch results alike. This is the contract that lets an integrator cite a federal fact, not just display it.

{
  "_source": "NPPES",
  "_source_url": "https://npiregistry.cms.hhs.gov",
  "_dataset_id": "nppes",
  "_snapshot": "2026-05-01",
  "_methodology": "resolver/v6",
  "_last_checked": "2026-05-27T00:00:00Z",
  "_confidence": 0.98,
  "_data_availability": ["present"],
  "_pipeline_version": "556ca10",
  "_doi": null,
  "_license": "US-Government-Works",
  "_coverage_period_start": "2005-05-23",
  "_coverage_period_end": "ongoing",
  "_slsa_provenance_url": null
}

The 14 keys

_doi and _slsa_provenance_url are null until the source has a minted DOI or a published build attestation — we return null rather than inventing a value.

MCP server

Agents do not write fetch calls — they call tools. The Fonteum Model Context Protocol server exposes the same resolvers as native MCP tools, so a LangGraph, Claude, or Perplexity agent can resolve an NPI, pull quality scores, or check an exclusion without you wiring HTTP by hand. Each tool result carries the full 14-tuple, unchanged.

Run it over stdio with npx; the key is read from FONTEUM_API_KEY and falls back to the sample key.

npx -y @fonteum/mcp

Add it to any MCP client by pointing the client at that command:

{
  "mcpServers": {
    "fonteum": {
      "command": "npx",
      "args": ["-y", "@fonteum/mcp"],
      "env": { "FONTEUM_API_KEY": "pk_dx_sample" }
    }
  }
}

Full framework-specific setup — Claude Desktop, LangGraph, Google ADK — lives on the agents page.

Rate limits & SLAs

Limits are per-key and per-hour. Every response carries the current budget in headers, so you can throttle proactively instead of reacting to 429s. The sandbox key is shared and unauthenticated, so treat its budget as best-effort.

curl -i https://api.fonteum.com/v1/npi/1234567890 \
  -H "X-Fonteum-Key: pk_dx_sample"

{
  "X-RateLimit-Limit": 100,
  "X-RateLimit-Remaining": 98,
  "X-RateLimit-Reset": 1730000000
}

Tiers

X-RateLimit-Reset is a Unix epoch second. On 429, prefer the Retry-After header over computing your own backoff.

Changelog

The API is versioned by URL prefix (/v1). Breaking changes ship behind a new prefix; everything below is additive within v1. Subscribe to the source.refreshed webhook to track data-snapshot changes, which are not versioned here.

Deprecations are announced here and in the source.refreshed payload at least 90 days before removal. Nothing in v1 is currently deprecated.