FHIR R4 Provider Directory API

NPPES + PECOS + Care Compare + HRSA — served as FHIR.

The Fonteum FHIR R4 endpoint gives EHRs, payer platforms, and analytics tools a single HL7-canonical interface to the fullFonteum provider graph — 7M+ NPI records from NPPES, facility data from CMS Care Compare (nursing homes, hospice, home health, dialysis), HRSA HPSA designations, OIG LEIE exclusion flags, and CMS QPP MIPS performance scores. Every field carries source, date, and limitation metadata.

Conformance levels:

• US Core 6.1.0 — ONC-mandated baseline for provider directory interoperability. 5 distinct USCDI v3 Provider resources declared in the CapabilityStatement.
• Da Vinci PDex Provider Directory — CMS Interoperability and Patient Access Final Rule (45 CFR §156.221). Payer network exposure via /fhir/r4/pdex/.
• FHIR Bulk Data Access v2.0.0 — Async system-level $export returning NDJSON with per-resource provenance tags.
• SMART Backend Services — client_credentials flow with signed JWT for authenticated access and bulk export.

One base URL. All resources, all profiles.

All FHIR R4 endpoints are served under:

https://mcp.fonteum.com/fhir/r4

The CapabilityStatement at https://mcp.fonteum.com/fhir/r4/metadata is the authoritative discovery document — it enumerates every supported resource, search parameter, and operation. Da Vinci PDex-profiled endpoints live under https://mcp.fonteum.com/fhir/r4/pdex/. The legacy base at https://fonteum.com/api/fhir remains available for backwards compatibility (e.g. https://fonteum.com/api/fhir/Practitioner, https://fonteum.com/api/fhir/Organization). All responses use Content-Type: application/fhir+json. Errors return FHIR-canonical OperationOutcome resources — not generic JSON error envelopes.

5 distinct USCDI v3 Provider resources. Source-backed.

Each resource is backed by one or more Fonteum federal source families. The logical id scheme and source family determine which identifier system to use when constructing read URLs.

All resources expose full search parameter sets. See /api/fhir/metadata for the authoritative parameter list per resource type.

Async $export. NDJSON. 14-tuple provenance on every line.

The $export operation implements the HL7 FHIR Bulk Data Access v2.0.0 implementation guide. A POST to https://mcp.fonteum.com/fhir/r4/$export returns HTTP 202 with a Content-Location status URL. Poll the status URL until "status": "completed", then download the NDJSON output files.

• Format: NDJSON — one FHIR resource JSON object per line, application/fhir+ndjson content type.
• Provenance: Every NDJSON line carries the same 14-tuple meta.tag contract as single-resource reads — source_id, snapshot_date, ingestion_run_id, methodology_version, license_spdx, and nine additional governance tags.
• Scope filters: _type limits the export to specific resource types. _since limits to resources updated after an ISO-8601 instant.
• Auth required: SMART Backend Services JWT (client_credentials flow) is required for all $export requests.
• Concurrency: 1 active job per client_id. Additional requests return HTTP 429 until the active job completes or is cancelled.

# Initiate a system-level $export (requires SMART Backend Services JWT)
curl -sX POST \
  -H "Authorization: Bearer <signed-jwt>" \
  -H "Accept: application/fhir+json" \
  -H "Prefer: respond-async" \
  "https://mcp.fonteum.com/fhir/r4/\$export?_type=Practitioner,Organization" \
  -I | grep -i content-location
# → Content-Location: https://mcp.fonteum.com/fhir/r4/$export/status/<job-id>

# Poll export status
curl -sH "Authorization: Bearer <signed-jwt>" \
  "https://mcp.fonteum.com/fhir/r4/\$export/status/<job-id>" | jq '.status'
# → "completed"
# Response includes output[] array of NDJSON file URLs

Anon reads. SMART Backend Services for $export.

The API has two auth tiers:

• Anonymous (read-only): All GET endpoints accept unauthenticated requests up to the anon rate limit (60 req/min/IP). Pass the public key in the X-Fonteum-Public-Key header to identify your client and receive a higher rate limit bucket: X-Fonteum-Public-Key: <MCP_PUBLIC_KEY>.
• SMART Backend Services (client_credentials): Required for $export and for sustained read workloads above the anon limit. Generate a client assertion JWT signed with your registered RSA-2048 or ES384 private key, exchange it for a Bearer token at the token endpoint, then pass Authorization: Bearer <token> on each request.

Token endpoint and JWKS registration URL are in the SMART configuration document:

# Retrieve the CapabilityStatement (no auth required)
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/metadata" | jq '.fhirVersion'
# → "4.0.1"

# SMART on FHIR discovery
curl -s "https://mcp.fonteum.com/fhir/r4/.well-known/smart-configuration" | jq '.token_endpoint'

Bearer tokens are short-lived (15 minutes). Rotate them using the client_credentials grant before expiry. The .well-known/smart-configuration endpoint is public and returns the token endpoint URL and supported scopes (system/*.read, system/$export).

curl — the minimal client for every endpoint.

Practitioner — search by NPI identifier

# Read a Practitioner by NPI (identifier token search)
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|1245319599" \
  | jq '.entry[0].resource.resourceType'
# → "Practitioner"

# Read a single Practitioner by logical id
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/Practitioner/1245319599" | jq '.name[0].family'
# → "SMITH"

# Search by family name
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/Practitioner?family=Smith&_count=20" | jq '.total'

Organization — search by name

# Search Organizations by name
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/Organization?name=Mercy+General" | jq '.entry[0].resource.name'
# → "MERCY GENERAL HOSPITAL"

# Filter by state
curl -sH "Accept: application/fhir+json" \
  "https://mcp.fonteum.com/fhir/r4/Organization?address-state=CA&_count=20" | jq '.total'

Bulk $export — initiate and poll

# Initiate a system-level $export (requires SMART Backend Services JWT)
curl -sX POST \
  -H "Authorization: Bearer <signed-jwt>" \
  -H "Accept: application/fhir+json" \
  -H "Prefer: respond-async" \
  "https://mcp.fonteum.com/fhir/r4/\$export?_type=Practitioner,Organization" \
  -I | grep -i content-location
# → Content-Location: https://mcp.fonteum.com/fhir/r4/$export/status/<job-id>

# Poll export status
curl -sH "Authorization: Bearer <signed-jwt>" \
  "https://mcp.fonteum.com/fhir/r4/\$export/status/<job-id>" | jq '.status'
# → "completed"
# Response includes output[] array of NDJSON file URLs

For Python (fhirclient), JavaScript (fhirpath), and R examples, see the full code samples section below, or the legacy bulk export reference.

14-tuple per field. Source, date, limitation — always.

Fonteum’s core trust contract: every rendered fact ties to a provider_field_provenance row in the database, which itself ties to a data_sources row. In FHIR resources, this contract is projected onto meta.tag as a set of Coding entries under the https://fonteum.com/fhir/CodeSystem/provenance-tag system.

The 14-tuple tags carried on every resource:

Full specification: /docs/provenance-contract. Integrity attestations (Ed25519 co-signatures per snapshot) are publicly readable at /trust/integrity.

60 req/min anon. 600 req/min authenticated.

Requests above the limit receive HTTP 429 with a Retry-After header (seconds until the next window). Rate limit headers on every response:

• X-RateLimit-Limit — limit for the current tier
• X-RateLimit-Remaining — requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets

SLA:The FHIR endpoint targets 99.9% uptime, measured monthly. Bulk $export jobs targeting the full Practitioner resource set (>7M records) complete within 30 minutes under normal load. Status pages and incident history: /trust.

For sustained workloads above the authenticated tier, contact /pilot-intake to discuss an enterprise SLA.

Related documentation.

• /api/fhir/metadata — live CapabilityStatement (US Core 6.1.0, 5 resources)
• /docs/provenance-contract — full 14-tuple provenance contract specification
• /docs/bulk-export — gzipped CSV bulk download surface (alternative to $export)
• /docs/researcher-api — REST API for research queries and dataset access
• /data-catalog — DCAT-US 3.0 dataset catalog
• /trust/integrity — SHA-256 snapshot attestations + Ed25519 co-signatures
• /cite — citation guidance + BibTeX templates

Common developer questions.