Audit-grade data via REST.

Programmatic access to Fonteum's source-provenanced provider supply data. Every response carries per-field provenance metadata — source URL, last-checked timestamp, confidence score, methodology link — so you can route the entire response through compliance review without a separate methodology lookup. Audit-grade is the architecture, not a feature.

Base URL: https://fonteum.com/api/v1 · OpenAPI: /api/v1/openapi.json · Status: /api/v1/health

• Quickstart
• Authentication
• Rate limits
• Provenance contract
• Subspecialty filter
• Error reference
• Changelog
• OpenAPI reference

Quickstart (5 minutes)

1. Request access at /data-platform/api-access. The operator approves manually within 1 business day during the pilot.
2. You receive your key by email (format: ownl_…). Copy it — it's shown once and stored only as a hash.
3. Send your first request:

curl https://fonteum.com/api/v1/specialties \
  -H "Authorization: Bearer ownl_YOUR_KEY"

Response is JSON with two top-level keys: data (the actual payload) and meta (request_id, api_version, data_freshness, methodology_url, limitations_url).

Authentication

Every authenticated endpoint requires a Bearer token in the Authorization header:

Authorization: Bearer ownl_YOUR_KEY

Public endpoints (/health, /openapi.json) do not require authentication. Missing keys return 401 with code missing_api_key; revoked or expired keys return 401 with invalid_api_key.

Rate limits

Pilot tier defaults:

• 1,000 requests / 24h rolling window
• 60 requests / minute rolling window

Every response (200 and 429 alike) carries:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 982
X-RateLimit-Reset:     2026-05-06T08:30:14.123Z
X-RateLimit-Window:    1d (rolling)

429 responses include a Retry-After: 60 header. The 429 itself is notcounted against your quota — retries don't escalate the lockout.

The provenance contract

Every API response carries provenance metadata at two levels:

1. Per-field — each value comes wrapped with its source, source URL, last-checked timestamp, confidence score (where applicable), attribution text, and per-field limitations callout.
2. Per-response — the meta envelope reports request ID, api_version, data_freshness (per source family), methodology_url, limitations_url, documentation_url, and any geo-scope caveats.

This is doctrine, not feature. The Council #2 critique was explicit: audit-grade trust positioning has to be the architecture or it's not credible. A buyer should be able to route every API response through their compliance review without a separate methodology lookup.

Sample response shape:

{
  "data": [
    {
      "state_code": {
        "value": "CA",
        "source": "CMS NPPES NPI Registry (public API)",
        "source_url": "https://npiregistry.cms.hhs.gov/api/",
        "last_checked": "2026-05-06T00:00:00Z",
        "attribution_text": "Source: CMS NPPES NPI Registry (public)."
      },
      "active_providers": {
        "value": 4521,
        "source": "CMS NPPES NPI Registry (public API)",
        "last_checked": "2026-05-06T00:00:00Z",
        "attribution_text": "Source: CMS NPPES NPI Registry (public)."
      },
      "population_2024": {
        "value": 39_364_774,
        "source": "U.S. Census Bureau PEP V2025",
        "last_checked": "2026-03-15T00:00:00Z"
      },
      "per_100k": {
        "value": 11.49,
        "source": "Fonteum Research (derived from CMS NPPES + U.S. Census)",
        "last_checked": "2026-05-06T00:00:00Z",
        "confidence_score": 0.95
      }
    }
  ],
  "meta": {
    "request_id": "req_8f2c1a4b",
    "api_version": "v1",
    "data_freshness": [
      { "source": "CMS NPPES NPI Registry (public API)",
        "last_refreshed": "2026-05-06T00:00:00Z",
        "cadence": "Quarterly" },
      { "source": "U.S. Census Bureau PEP V2025",
        "last_refreshed": "2026-03-15T00:00:00Z",
        "cadence": "Annual" }
    ],
    "methodology_url": "https://fonteum.com/research/dermatology-provider-supply-by-state-2026#methodology",
    "limitations_url": "https://fonteum.com/research/dermatology-provider-supply-by-state-2026#limitations",
    "documentation_url": "https://fonteum.com/docs/api#tag/Specialties"
  }
}

Subspecialty filter (§193)

/specialties/{code}/by-state and /specialties/{code}/by-county accept an optional ?subspecialty=<NUCC code> query parameter. When supplied, counts, per_100k, rank_density, and quartile are recomputed against NPPES providers whose taxonomy_codes array includes the requested code.

# Procedural Dermatology / MOHS slice of the dermatology supply data:
curl "https://fonteum.com/api/v1/specialties/dermatology/by-state?subspecialty=207NS0135X" \
  -H "Authorization: Bearer ownl_YOUR_KEY"

Supported codes per primary specialty are listed in the OpenAPI spec under each endpoint's description. Unknown codes return 400 invalid_subspecialty with the supported list.

Coverage caveat. Three primary specialties have multiple distinct taxonomies in the cache and produce meaningful filter results — dermatology, obgyn, pediatrics. The other 9 specialties have a single-taxonomy cache; on those, ?subspecialty= either matches the parent code or returns zero rows. The next NPPES re-ingest will widen the scope.

Underserved threshold note. The parent study's underserved threshold (per study) does not transfer to a subspecialty slice — filtered rows always emit underserved: false. Use per_100k + rank_density for relative comparisons within the slice.

When a filter is applied, meta.subspecialty_filter reports the applied code, display name, and matched record count.

Error reference

All errors follow the same envelope:

{
  "error": { "code": "rate_limit_exceeded", "message": "...", "details": {...} },
  "meta": { "request_id": "req_...", "api_version": "v1" }
}

Changelog

• v1.0 — 2026-05-06. Initial release. 7 endpoints (health, openapi.json, specialties, specialties/[code]/by-state, specialties/[code]/by-county, states/[state]/coverage, providers/[npi], methodology/[dataset]). Bearer-token auth. Per-field provenance contract. Pilot rate limits (1,000/day, 60/min). OpenAPI 3.0 spec. Operator-approved access only.

OpenAPI reference

Rendered from /api/v1/openapi.json via Redoc. Click any endpoint for request/response details and try-it samples.