Public records your app can re-check.

Getting started

Run your first authenticated request against a deterministic synthetic provider fixture. The sample key fnt_DEMO_PUBLIC_V1 is live, read-only, and limited to 20 requests/minute and 100 requests/day per trusted source IP. Swap it for your own fnt_ key when you move past the sandbox.

The base URL is https://api.fonteum.com/v1. Consult the current endpoint documentation for its access requirements. Responses are JSON and expose the source, observation date, and other provenance fields available for that route. No provenance fact currently links deterministically to a signature.

curl https://api.fonteum.com/v1/npi/1234567893 \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

{
  "npi": "1234567893",
  "type": "organization",
  "organization_name": "EXAMPLE MEDICAL CENTER",
  "address": { "city": "AUSTIN", "state": "TX", "postal_code": "78701" },
  "is_excluded_oig": null,
  "exclusion_coverage_status": "indeterminate",
  "exclusion_determination": "indeterminate",
  "_source": "Synthetic demo fixture — not a live source record",
  "_source_url": null,
  "_dataset_id": "synthetic-demo-npi",
  "_snapshot": null,
  "_methodology": "synthetic-demo-v1",
  "_last_checked": null,
  "_data_availability": "synthetic_demo_fixture; exclusion_coverage_indeterminate",
  "_confidence": null,
  "_pipeline_version": null,
  "_doi": null,
  "_license": "Synthetic example; no source-record license asserted",
  "_coverage_period_start": null,
  "_coverage_period_end": null,
  "_slsa_provenance_url": null
}

The response is deliberately synthetic and issues no live exclusion clearance. It illustrates fields that supported NPPES, OIG LEIE, CMS PECOS, CMS Care Compare, and CMS Open Payments responses can expose. Source blocks and provenance fields vary by identifier and can be null; use an account key with a real NPI for source-resolved data. The next sections cover authentication, each resolver, and the nullable provenance contract.

Authentication

Get a key: create a free account at /account/signup — no card, 2,500 grounded retrievals a month. Pass it as Authorization: Bearer fnt_…. Manage keys, watch usage against your quota, and upgrade from your dashboard. Usage is metered per key — a grounded retrieval is one credit, a /verify re-check a quarter credit; see pricing and the API Terms of Use.

Pass your key in the Authorization header as Bearer fnt_<opaque> on every protected request. There is no OAuth exchange for REST API keys. 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/1234567893 \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

A missing or unknown key returns 401; exceeding either the minute or day window returns 429 with a Retry-After header.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid, revoked, or expired."
  },
  "meta": {
    "request_id": "req_8Fk2pQ",
    "api_version": "v1"
  }
}

Plan tiers

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

Resolve a provider by NPI

The NPI resolver accepts a 10-digit National Provider Identifier and returns the public NPPES record. It can add enrollment, exclusion, quality, or payment rows only where those sources publish the same NPI; sources keyed by CCN, license number, name, or another identifier are not treated as deterministic NPI matches.

curl https://api.fonteum.com/v1/npi/1234567893 \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

{
  "npi": "1234567893",
  "type": "organization",
  "organization_name": "EXAMPLE MEDICAL CENTER",
  "address": { "city": "AUSTIN", "state": "TX", "postal_code": "78701" },
  "is_enrolled_medicare": true,
  "is_excluded_oig": null,
  "exclusion_coverage_status": "indeterminate",
  "exclusion_determination": "indeterminate",
  "_source": "Synthetic demo fixture — not a live source record",
  "_source_url": null,
  "_dataset_id": "synthetic-demo-npi",
  "_snapshot": null,
  "_methodology": "synthetic-demo-v1",
  "_last_checked": null,
  "_data_availability": "synthetic_demo_fixture; exclusion_coverage_indeterminate",
  "_confidence": null,
  "_pipeline_version": null,
  "_doi": null,
  "_license": "Synthetic example; no source-record license asserted",
  "_coverage_period_start": null,
  "_coverage_period_end": null,
  "_slsa_provenance_url": null
}

The sample NPI returns a synthetic fixture and no live exclusion clearance. With a real NPI, the resolver returns source-resolved data; an unknown NPI returns 404 not_found. After successful authentication, malformed identifiers (wrong length, non-numeric) return 400 invalid_npi before data lookup.

Resolve an NPI crosswalk link by CCN

The deployed CCN operation is GET /v1/entity/ccn/{ccn}. It returns a canonical CCN-to-NPI crosswalk link and its matching evidence; it does not return a facility record or Care Compare quality measures.

Template only — no fixed CCN fixture is guaranteed. Set FONTEUM_CCN to a CCN present in the canonical crosswalk and use an account key. The sample key is guaranteed only for the documented demo NPI request.

curl "https://api.fonteum.com/v1/entity/ccn/${FONTEUM_CCN}" \
  -H "Authorization: Bearer ${FONTEUM_API_KEY}"

The deployed response contains ccn, npi, link_method, link_confidence, link_tier, source_table, methodology_version, and attested_at. A missing canonical link returns 404. CCNs may be 6 or 10 alphanumeric characters; other shapes return 400.

Search records

When you do not yet have an identifier, search by name. The lookup returns grouped candidate records — providers, hospitals, trials, studies, and resolved entity-graph entities — each with a canonical destination route. Resolve the record you want for the full provenance-backed payload.

curl "https://api.fonteum.com/v1/search?q=mayo%20clinic&limit=3" \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

{
  "providers": [],
  "hospitals": [],
  "trials": [],
  "studies": [],
  "entities": [
    {
      "id": "ef5ca2bb-3bb6-40dc-abec-d82133cafdb9",
      "type": "entity",
      "name": "MAYO CLINIC HOSPITAL",
      "subtitle": "facility · ccn 030103 · AZ",
      "href": "/terminal/entity/ef5ca2bb-3bb6-40dc-abec-d82133cafdb9",
      "dataset_id": "entity-graph",
      "_last_checked": null
    }
  ]
}

limit caps each group (1–10, default 3). entities rows are canonical entities in the resolved graph — their href opens the Terminal entity card with cross-source identifiers, link confidence on every attachment, and retained row history only where the named source has banked versions. This is not universal replay for every entity or date. Identifier-shaped queries (an NPI, a CCN) probe the graph directly; protected search requests require a valid Bearer key and use the key’s configured rate limits.

Cross-dataset facts — contract preview

Contract preview — not currently deployed. include=facts is not an active GET /v1/npi/{npi} query option, and no runnable facts[] response is available today.

The planned contract would return independently provenance-bound facts instead of flattening assertions from different source families into one value. Until that projection is deployed, use the deployed GET /v1/npi/{npi} operation and the dataset-specific routes listed in the OpenAPI document.

No sample credential or fixed response is shown here because this contract cannot be executed against the live API.

Data quality scorecard

The deployed quality operation returns Fonteum's machine-readable data-quality scorecard. It is an explicitly public, read-only route; no key is required.

curl https://api.fonteum.com/v1/quality

The live response carries generated_at, composite_score, completeness, consistency, timeliness, oig_leie_match_rate, and _methodology. Scorecard values are computed from the current serving data and therefore are not hard-coded in this reference.

Per-facility paths such as /v1/quality/hospital/{ccn} are not deployed.

Open Payments

CMS Open Payments discloses industry transfers of value to physicians and teaching hospitals. The contract below previews an NPI-level aggregation plus underlying records.

Contract preview — not currently deployed. /v1/payments/{npi} is not in the current v1 route inventory. The request and response below are illustrative and are not produced by the public sample key today.

GET /v1/payments/<npi>  # illustrative contract; not currently deployed

Illustrative response shape:

{
  "npi": "<npi>",
  "program_year": 2024,
  "total_amount_usd": 18420.55,
  "record_count": 37,
  "records": [
    {
      "manufacturer": "EXAMPLE MANUFACTURER",
      "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
}

If deployed with name-and-address matching rather than a direct NPI field, _confidence would need to disclose match strength. Records below the CMS de-minimis threshold are excluded by the publisher.

Batch resolution availability

No POST /api/v1/batch/npi endpoint is currently published. Do not send a panel to that path or rely on the previously documented request limits.

For now, resolve identifiers individually through their documented routes, or use the nine-tool MCP surface where it suits the workflow. A batch contract will appear in OpenAPI before it is advertised here.

Webhooks — delivery contract preview

Contract preview — not currently deployed. Fonteum does not currently expose a public webhook subscription or delivery service, and webhooks.fonteum.com is not an active delivery endpoint.

The planned contract would notify a customer-controlled endpoint when a source snapshot changes. A future delivery would be authenticated with a delivery signature, not with the customer's REST API Bearer credential.

The payload and event catalog remain design material only. No retry, delivery, or subscription behavior is available today, so this page intentionally provides no runnable curl command.

Errors

Authentication, quota, and standard withApi errors use the envelope below: an error object with a stable machine code and human message, plus meta.request_id to quote in support. Individual streaming/raw endpoints document any route-local validation shape in their own reference. HTTP status follows convention — 4xx is your request, 5xx is ours.

curl -i https://api.fonteum.com/v1/npi/0000000000 \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

{
  "error": {
    "code": "provider_not_found",
    "message": "No provider with NPI 0000000000 found in the CMS NPPES NPI Registry."
  },
  "meta": {
    "request_id": "req_8Fk2pQ",
    "api_version": "v1"
  }
}

Codes

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

Provenance contract

Fonteum responses expose a 14-key provenance schema. The keys are nullable, and their population varies by source, endpoint, and record; use only values present in the response. The underscore prefix prevents collisions with source field names. When populated, these fields let an integrator cite the named source and observation date.

{
  "_source": "NPPES",
  "_source_url": "https://npiregistry.cms.hhs.gov",
  "_dataset_id": "nppes",
  "_snapshot": null,
  "_methodology": "resolver/v6",
  "_last_checked": null,
  "_confidence": null,
  "_data_availability": ["present"],
  "_pipeline_version": null,
  "_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 call Fonteum tools instead of hand-writing API requests. The hosted Model Context Protocol server exposes nine read-only tools for US healthcare providers, federal contractors, exclusions, sanctions, source catalogs, and snapshot re-checks. Tool descriptions start with the question each tool is meant to answer so an agent can select the narrowest operation.

The hosted endpoint is https://fonteum.com/api/mcp and advertises MCP server version 1.1.0. Every tool has annotations.readOnlyHint: true. The stdio source targets @fonteum/mcp@0.5.0, which is pending operator publication; npm currently serves 0.4.0. Do not use the command or config below until the operator publishes 0.5.0.

FONTEUM_API_KEY="$FONTEUM_API_KEY" npx -y @fonteum/mcp@0.5.0

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

Full client setup lives on the agents page.

Canonical tools

Response contract

Every successful or failed tool response includes JSON text plus matching MCP structuredContent. These four keys are always present at the top level:

• source_file: string | null — exact retained source filename when one file honestly represents the response.
• as_of_date: string | null — source publish or snapshot date; never the request time substituted for missing source metadata.
• snapshot_digest: string | null — digest for an identified retained snapshot object; never a per-fact signature or live-chain-head substitute.
• verifiable_url: string — public source, methodology, or snapshot re-check URL appropriate to the response.

Composite results and errors use null when one source file, date, or digest does not honestly represent the response. Per-source details remain inside the returned data and provenance blocks.

Package REST bridges

The future stdio package calls these deployed routes under https://fonteum.com/api using Authorization: Bearer $FONTEUM_API_KEY where required:

• GET /api/v1/npi/{npi} — fonteum_lookup_npi.
• GET /api/v1/procurement/screen?uei={uei} or GET /api/v1/procurement/screen?cage={cage} — fonteum_lookup_contractor (pass exactly one identifier).
• GET /api/v1/mcp/search-records?vertical={slug}&state={USPS}&county={optional}&limit={1..100} — fonteum_search_providers.
• GET /api/v1/exclusions/{npi} — fonteum_check_exclusion.
• GET /api/sanctions/screen?q={name} — fonteum_search_sanctions.
• GET /api/v1/procurement/screen?as_of={YYYY-MM-DD}&uei={uei} or GET /api/v1/procurement/screen?as_of={YYYY-MM-DD}&cage={cage} — fonteum_lookup_contractor_history (pass exactly one identifier).
• GET /api/v1/mcp/recheck?snapshot_id={optional-positive-integer} — fonteum_recheck_snapshot.
• GET /api/v1/sources — fonteum_list_sources.
• GET /api/v1/mcp/dataset-info — no-argument fonteum_get_dataset_info.

For fonteum_lookup_npi, only an explicit zero-result response from CMS NPPES is a not-found result. If NPPES cannot answer reliably or returns an invalid payload, the REST bridge returns 503 nppes_unavailable and the MCP error identifies the lookup as indeterminate. Do not interpret that error as provider absence.

The REST bridges are not substitutes for an MCP JSON-RPC session; they keep the future stdio package and the hosted tools on the same data contract.

Rate limits & SLAs

Limits use rolling per-minute and per-day windows. Every authenticated response carries the current budget in headers, so you can throttle proactively instead of reacting to 429s. The shared sample credential is limited to 20 requests/minute and 100 requests/day per trusted source IP.

curl -i https://api.fonteum.com/v1/npi/1234567893 \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1"

{
  "X-RateLimit-Limit-Minute": 20,
  "X-RateLimit-Remaining-Minute": 18,
  "X-RateLimit-Limit-Day": 100,
  "X-RateLimit-Remaining-Day": 98,
  "X-RateLimit-Limit": 100,
  "X-RateLimit-Remaining": 98,
  "X-RateLimit-Reset": 1730000000,
  "X-RateLimit-Reset-At": "2024-10-27T03:33:20.000Z"
}

Tiers

The compatibility X-RateLimit-Limit and X-RateLimit-Remaining headers mirror the day window. X-RateLimit-Reset is a Unix epoch second; X-RateLimit-Reset-At is the same reset as an ISO timestamp. On 429, prefer the Retry-After header over computing your own backoff.

Changelog

The API is versioned by URL prefix (/v1). Breaking changes normally ship behind a new prefix. The FND-010 status reconciliation below is a documented corrective exception: the previous status fields contradicted each other, so summary.overall now carries the shared canonical operational state and the former source-only assessment is preserved as summary.findings_state. Current source status is available from GET /v1/status; the webhook delivery contract remains a non-deployed preview.

Deprecations are announced here at least 90 days before removal. Nothing in v1 is currently deprecated.