Do I need authentication to access the Fonteum FHIR R4 API?

No. The API supports anonymous access for read operations (GET) using the public anon key (MCP_PUBLIC_KEY). For Bulk Data Access ($export) and write-eligible operations, SMART Backend Services auth via a signed JWT Bearer token is required.

What is the rate limit for the Fonteum FHIR R4 API?

Anonymous reads: 60 requests per minute per IP. Authenticated requests (SMART Backend Services JWT): 600 requests per minute per client_id. Bulk $export jobs: 1 concurrent job per client_id. Sustained usage above these limits returns HTTP 429 with a Retry-After header.

Developer Documentation · FHIR R4

FHIR R4 Provider Directory API

Q: Which FHIR implementation guides does Fonteum conform to?

Fonteum conforms to US Core 6.1.0 (the ONC-mandated baseline for provider directory interoperability), Da Vinci PDex Provider Directory (CMS Interoperability Final Rule 45 CFR 156.221), and the HL7 FHIR Bulk Data Access v2.0.0 implementation guide for $export.

Q: How is provenance metadata encoded in FHIR resources?

Supported FHIR resources can expose source-level provenance Coding entries in meta.tag. Tag availability varies by resource builder and source; values may be null or absent, and a resource tag is not an individual-field signature.

Fonteum exposes its federated healthcare provider graph as a standards-conformant FHIR R4 API. US Core 6.1.0, Da Vinci PDex, Bulk Data Access ($export), and SMART Backend Services auth. Supported resources expose source-level provenance tags where available.

CapabilityStatement → Provenance contract → Bulk export →

Quickstart

Read your first provider resource in 5 minutes.

No API key required.

Step 1 — Discover the API

curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/metadata" | jq '.rest[0].resource[].type'
# Expected: ["Practitioner","PractitionerRole","Organization","Location","HealthcareService"]

Step 2 — Read a Practitioner by NPI

Replace 1073662946 with any 10-digit NPI. The NPI Registry is public at npiregistry.cms.hhs.gov.

curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/Practitioner/1073662946" | jq '{name:.name,id:.id}'

Step 3 — Get roles for a practitioner

PractitionerRole search requires a practitioner or organization anchor. Pass the NPI as the practitioner parameter.

curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/PractitionerRole?practitioner=1073662946&_count=5" \
  | jq '.entry[].resource.practitioner.reference'

Step 4 — Inspect available provenance tags

curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/Practitioner/1073662946" | jq '.meta.tag'

A supported resource can carry meta.tag entries for source family, snapshot date, methodology version, and other available provenance fields. Tags vary by builder and can be absent. See the Provenance section for the complete field reference.

For bulk export with SMART Backend Services authentication, see the Bulk Data Access section — it requires JWT signing and is not a 5-minute quickstart.

1. Overview

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 — 6.8M+ active 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. Source, date, and limitation metadata is returned only where the participating resource supplies it.

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 /api/fhir/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.

2. Base URL

One base URL. All resources, all profiles.

All FHIR R4 endpoints are served under:

https://fonteum.com/api/fhir

The CapabilityStatement at https://fonteum.com/api/fhir/metadata is the authoritative discovery document — it enumerates every supported resource, search parameter, and operation. Da Vinci PDex-profiled endpoints live under https://fonteum.com/api/fhir/pdex/. All responses use Content-Type: application/fhir+json. Errors return FHIR-canonical OperationOutcome resources — not generic JSON error envelopes.

3. Supported resources

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.

Resource	Logical id	Source family	Notes
`Practitioner`	NPI (10-digit)	NPPES, CMS PECOS PPEF, CMS QPP MIPS	Identifier system: `http://hl7.org/fhir/sid/us-npi`
`Organization`	NPI (10-digit) · CCN (6-char, legacy)	CMS PECOS PPEF (433,496 enrolled organizations — rows where `org_name IS NOT NULL`); CMS Care Compare (Nursing Home, Hospice, Home Health, Dialysis) + CMS POS iQIES for CCN-keyed facilities	Identifier systems: `http://hl7.org/fhir/sid/us-npi` (primary), `http://hl7.org/fhir/sid/us-ccn`. Individual-provider NPIs (where `org_name` is absent) return 404 — use `Practitioner/{npi}` for those.
`PractitionerRole`	`prr-{NPI}-{CCN\|solo}`	NPPES + CMS Care Compare (join)	Links a Practitioner to an Organization at a Location.`solo` when no facility affiliation.
`Location`	`{sourceType}-{sourceKey}`	NPPES (npi-prefixed), CMS Care Compare (ccn-prefixed), HRSA HPSA (hpsa-prefixed)	sourceType ∈ `{ccn, npi, hpsa}`
`HealthcareService`	`hs-{NPI}`	NPPES taxonomy codes, HRSA HPSA	NUCC provider taxonomy → FHIR specialty mapping. Methodology pinned at `us-core-healthcare-service/v1`.

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

4. Bulk export

Async $export. NDJSON. Resource-specific provenance where available.

The $export operation implements the HL7 FHIR Bulk Data Access v2.0.0 implementation guide. A POST to https://fonteum.com/api/fhir/$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: An NDJSON resource can carry themeta.tag entries available from its resource builder. Tag sets and nullable values vary by source; they are not per-field signatures.
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://fonteum.com/api/fhir/\$export?_type=Practitioner,Organization" \
  -I | grep -i content-location
# → Content-Location: https://fonteum.com/api/fhir/$export/status/<job-id>

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

5. Authentication

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 private key (RS256) and present it directly as the Bearer token: Authorization: Bearer <signed-jwt>.

The SMART configuration discovery document is public:

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

# SMART on FHIR discovery
curl -s "https://fonteum.com/api/fhir/.well-known/smart-configuration" | jq '.capabilities'
# → ["client-public", "permission-patient", "permission-user"]

Required claims on the client assertion JWT — requests failing any check are rejected:

iss = sub = your registered client_id.
aud = https://fonteum.com/api/fhir (string or array member).
exp — in the future and no more than 5 minutes ahead (the SMART Backend Services token lifetime cap). Mint a fresh assertion per request batch.
jti — required and single-use; a replayed jti is rejected.

Granted scopes (system/*.read, system/$export) are bound to your registered client_id.

6. Code examples

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://fonteum.com/api/fhir/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://fonteum.com/api/fhir/Practitioner/1245319599" | jq '.name[0].family'
# → "SMITH"

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

Organization — read by NPI, search by name + state

# Read a provider Organization by NPI (CMS PECOS PPEF — 433,496 enrolled organizations)
# Note: NPI must belong to an organization (org_name present in PECOS).
# An individual-provider NPI returns 404 — use /Practitioner/{npi} for those.
curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/Organization?identifier=http://hl7.org/fhir/sid/us-npi|1003000126" \
  | jq '.entry[0].resource.name'

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

# Filter by state
curl -sH "Accept: application/fhir+json" \
  "https://fonteum.com/api/fhir/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://fonteum.com/api/fhir/\$export?_type=Practitioner,Organization" \
  -I | grep -i content-location
# → Content-Location: https://fonteum.com/api/fhir/$export/status/<job-id>

# Poll export status
curl -sH "Authorization: Bearer <signed-jwt>" \
  "https://fonteum.com/api/fhir/\$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.

7. Provenance

Nullable provenance tags at resource level.

Where a supported record has source metadata, FHIR resource builders can project available provenance fields onto meta.tag as a set of Coding entries under the https://fonteum.com/fhir/CodeSystem/provenance-tag system. Coverage varies by source and resource, fields may be null, and these tags do not assert a signature on each returned fact.

The schema permits the following tags when available:

Tag code	Description
`source_id`	Fonteum source family slug (e.g. cms-nppes, cms-care-compare)
`snapshot_date`	ISO-8601 date of the ingested upstream snapshot
`ingestion_run_id`	UUID of the ingestion_runs row — reproducible
`field_name`	Canonical field name (e.g. name.family, address.city)
`raw_value_hash`	SHA-256 of the raw upstream value before normalization
`methodology_version`	Pinned methodology version string (e.g. us-core-practitioner/v1)
`license_spdx`	SPDX license identifier (US-Government-Works or CC-BY-4.0)
`jurisdiction`	CMS jurisdiction or NPPES region code
`refresh_cadence`	Expected refresh frequency (daily, weekly, monthly, quarterly)
`limitation`	Known limitation or caveat for this field
`displayable`	Boolean — whether the field passes provider_field_displayable view
`witness_signature`	Ed25519 co-signature reference (snapshot_witness_signatures)
`cite_url`	Canonical citation URL for this snapshot
`attestation_url`	SHA-256 hash-match endpoint (/attest/<snapshot-id>)

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

8. Rate limits and SLA

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

Tier	Limit	Scope
Anonymous	60 req / min	Per IP address
Public key (MCP_PUBLIC_KEY)	300 req / min	Per key
SMART Backend Services (JWT Bearer)	600 req / min	Per client_id
$export concurrency	1 active job	Per client_id

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.

Common developer questions.

Do I need authentication to access the API?

No. All GET endpoints support anonymous access up to 60 requests per minute per IP. Pass X-Fonteum-Public-Key: <MCP_PUBLIC_KEY> to lift the limit to 300 req/min. SMART Backend Services JWT auth (600 req/min) is required only for $export.

Which FHIR implementation guides does Fonteum conform to?

US Core 6.1.0 (ONC-mandated baseline), Da Vinci PDex Provider Directory (CMS Interoperability Final Rule 45 CFR 156.221), and the HL7 FHIR Bulk Data Access v2.0.0 IG for $export.

How is provenance metadata encoded in FHIR resources?

Supported resources can expose source-level provenance in meta.tag as Coding entries under the Fonteum provenance CodeSystem URI. Tag sets vary by builder and source, and values can be null or absent. See /docs/provenance-contract for the full spec.

What is the rate limit for the FHIR API?

Anonymous: 60 req/min/IP. Public key: 300 req/min/key. SMART Backend Services JWT: 600 req/min/client_id. Bulk $export: 1 concurrent job per client_id. Sustained enterprise workloads: contact /pilot-intake.