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 seven-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 do not write fetch calls — they call tools. The Fonteum Model Context Protocol server exposes seven read-only tools for public records across healthcare, federal procurement, sanctions and watchlists, enforcement, and corporate and securities records. Tool results identify their source, capture date, and limitations where present.

The hosted endpoint is https://fonteum.com/api/mcp, advertises MCP server version 1.0.0, and permits anonymous, rate-limited access. The stdio source targets @fonteum/mcp@0.4.0, which is not yet published; the command and config below are for use after operator publication. Its protected REST bridges send Authorization: Bearer fnt_...; the read-only fnt_DEMO_PUBLIC_V1 key runs the documented demo path, and an account key supplies account-specific limits.

npx -y @fonteum/mcp@0.4.0

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

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

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

Canonical tools

• fonteum_resolve_entity
• fonteum_search_records
• fonteum_check_exclusions_and_sanctions
• fonteum_get_record_as_of
• fonteum_recheck
• fonteum_list_sources
• fonteum_dataset_info

Package REST bridges

The package uses three documented, Bearer-protected REST bridges whose schemas match hosted MCP:

• GET /api/v1/mcp/search-records?vertical={slug}&state={USPS}&county={optional}&limit={1..100} — fonteum_search_records.
• GET /api/v1/mcp/recheck?snapshot_id={optional-positive-integer} — fonteum_recheck.
• GET /api/v1/mcp/dataset-info — no-argument fonteum_dataset_info.

They are not substitutes for an MCP JSON-RPC session; they exist so the released stdio package and hosted tool results remain on one 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 ship behind a new prefix; everything below is additive within v1. 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.