{ "info": { "name": "Fonteum API", "description": "Fonteum — the source-lineage layer for provider data. Programmatic access to source-provenanced provider supply data. Every response carries per-field provenance metadata: source URL, last-checked timestamp, confidence score (where applicable), and methodology link. Audit-grade trust is the architecture, not a feature.\n\nAccess is operator-approved during the pilot. Request a key at https://fonteum.com/pilot-intake.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_postman_id": "fonteum-api-v1" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{FONTEUM_KEY}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://plumberproslist.com/api/v1" }, { "key": "FONTEUM_KEY", "value": "", "type": "string" } ], "item": [ { "name": "Health", "description": "Service health and per-source freshness.", "item": [ { "name": "Service health + per-source freshness", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/health", "host": [ "{{baseUrl}}" ], "path": [ "health" ], "variable": [] }, "description": "Public endpoint. Reports last successful refresh per source family." } }, { "name": "OpenAPI 3.0 spec", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/openapi.json", "host": [ "{{baseUrl}}" ], "path": [ "openapi.json" ], "variable": [] }, "description": "Public. Returns this document." } }, { "name": "Dataset freshness manifest", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/freshness", "host": [ "{{baseUrl}}" ], "path": [ "freshness" ], "variable": [] }, "description": "Returns per-dataset freshness status, row counts, and last-ingested timestamps for all 19 federal source families. No authentication required." } }, { "name": "System status (freshness + uptime)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/status", "host": [ "{{baseUrl}}" ], "path": [ "status" ], "variable": [] }, "description": "Aggregated system status: per-dataset freshness + rolling 30-day endpoint uptime. No authentication required." } } ] }, { "name": "Specialties", "description": "Medical specialty supply data (NPPES + Census).", "item": [ { "name": "List all available specialties", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/specialties", "host": [ "{{baseUrl}}" ], "path": [ "specialties" ], "variable": [] } } }, { "name": "Per-state density for one specialty", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/specialties/:code/by-state", "host": [ "{{baseUrl}}" ], "path": [ "specialties", ":code", "by-state" ], "variable": [ { "key": "code", "value": "" } ], "query": [ { "key": "subspecialty", "value": "207NS0135X", "description": "NUCC taxonomy code to filter on. Must be registered for the primary specialty (see endpoint description). Example: `207NS0135X` (Procedural Dermatology / MOHS) for primary `dermatology`." } ] }, "description": "Returns 51 rows (50 states + DC) with per-field provenance.\n\n**Optional `subspecialty` filter (§193).** When supplied, the response is recomputed against NPPES providers whose `taxonomy_codes` array includes the requested NUCC code. Counts, `per_100k`, `rank_density`, and `quartile` are recomputed from the filtered slice. The parent study's underserved threshold doesn't transfer, so filtered rows always carry `underserved: false`.\n\nSupported `subspecialty` codes per primary specialty (built from §183 / §188 specialty-study configs — same taxonomies the underlying ingest scoped to):\n\n- **cardiology**: single-taxonomy ingest (`207RC0000X` — Internal Medicine, Cardiovascular Disease (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **dermatology** (5 taxonomies):\n - `207N00000X` — Dermatology (parent)\n - `207ND0900X` — Dermatopathology\n - `207NI0002X` — Clinical & Laboratory Dermatological Immunology\n - `207NP0225X` — Pediatric Dermatology\n - `207NS0135X` — Procedural Dermatology / MOHS\n- **gastroenterology**: single-taxonomy ingest (`207RG0100X` — Internal Medicine, Gastroenterology). `?subspecialty=` either matches the parent or returns zero rows.\n- **neurology**: single-taxonomy ingest (`2084N0400X` — Psychiatry & Neurology, Neurology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **obgyn** (3 taxonomies):\n - `207V00000X` — Obstetrics & Gynecology (parent)\n - `207VX0000X` — Obstetrics & Gynecology, Obstetrics\n - `207VG0400X` — Obstetrics & Gynecology, Gynecology\n- **oncology**: single-taxonomy ingest (`207RX0202X` — Internal Medicine, Medical Oncology). `?subspecialty=` either matches the parent or returns zero rows.\n- **ophthalmology**: single-taxonomy ingest (`207W00000X` — Ophthalmology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **orthopedic**: single-taxonomy ingest (`207X00000X` — Orthopaedic Surgery (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **otolaryngology**: single-taxonomy ingest (`207Y00000X` — Otolaryngology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **pediatrics** (20 taxonomies):\n - `208000000X` — Pediatrics (parent)\n - `2080A0000X` — Pediatrics, Adolescent Medicine\n - `2080P0006X` — Pediatrics, Developmental — Behavioral Pediatrics\n - `2080P0008X` — Pediatrics, Neurodevelopmental Disabilities\n - `2080N0001X` — Pediatrics, Neonatal-Perinatal Medicine\n - `2080P0202X` — Pediatrics, Pediatric Cardiology\n - `2080P0203X` — Pediatrics, Child Abuse Pediatrics\n - `2080P0204X` — Pediatrics, Pediatric Emergency Medicine\n - `2080P0205X` — Pediatrics, Pediatric Hematology-Oncology\n - `2080P0206X` — Pediatrics, Pediatric Endocrinology\n - `2080P0207X` — Pediatrics, Pediatric Hematology-Oncology (alt)\n - `2080P0208X` — Pediatrics, Pediatric Infectious Diseases\n - `2080P0210X` — Pediatrics, Pediatric Pulmonology\n - `2080P0214X` — Pediatrics, Pediatric Rheumatology\n - `2080P0216X` — Pediatrics, Pediatric Sports Medicine\n - `2080I0007X` — Pediatrics, Pediatric Infectious Diseases (alt)\n - `2080S0010X` — Pediatrics, Sleep Medicine\n - `2080S0012X` — Pediatrics, Sports Medicine\n - `2080T0002X` — Pediatrics, Pediatric Transplant Hepatology\n - `2080H0002X` — Pediatrics, Hospice and Palliative Medicine\n- **psychiatry**: single-taxonomy ingest (`2084P0800X` — Psychiatry (individual provider)). `?subspecialty=` either matches the parent or returns zero rows.\n- **urology**: single-taxonomy ingest (`208800000X` — Urology (parent)). `?subspecialty=` either matches the parent or returns zero rows." } }, { "name": "Per-county aggregate (state-level density proxy)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/specialties/:code/by-county", "host": [ "{{baseUrl}}" ], "path": [ "specialties", ":code", "by-county" ], "variable": [ { "key": "code", "value": "" } ], "query": [ { "key": "state", "value": "CA", "description": "" }, { "key": "county_fips", "value": "06037", "description": "" }, { "key": "subspecialty", "value": "207NS0135X", "description": "NUCC taxonomy code to filter on. See `/specialties/{code}/by-state` description for the per-primary registry." } ] }, "description": "NPPES does not publish a county-level field of practice in its public API. Responses surface the parent state's density figure with the county context preserved in `meta.geo_scope_note`. Mirrors the §191 Access Gap Lookup Tool's honesty disclosure.\n\n**Optional `subspecialty` filter (§193).** Same semantics as `/specialties/{code}/by-state` — the recomputed slice is intersected with the requested state, and the resulting state-level row is returned in `data.state_level_supply`." } } ] }, { "name": "States", "description": "Per-state coverage rollups.", "item": [ { "name": "Combined per-specialty coverage for one state", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/states/:state/coverage", "host": [ "{{baseUrl}}" ], "path": [ "states", ":state", "coverage" ], "variable": [ { "key": "state", "value": "" } ] } } } ] }, { "name": "Providers", "description": "Single-provider lookup.", "item": [ { "name": "Single provider lookup by NPI", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/providers/:npi", "host": [ "{{baseUrl}}" ], "path": [ "providers", ":npi" ], "variable": [ { "key": "npi", "value": "" } ] } } } ] }, { "name": "Methodology", "description": "Dataset methodology metadata.", "item": [ { "name": "Methodology metadata for a dataset", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/methodology/:dataset", "host": [ "{{baseUrl}}" ], "path": [ "methodology", ":dataset" ], "variable": [ { "key": "dataset", "value": "" } ] } } } ] }, { "name": "Audit Pack", "description": "Per-dataset compliance artifact (§194). Versioned methodology, per-field provenance map, reproducibility, limitations, change history, downloadable PDF + JSON.", "item": [ { "name": "List all available Audit Packs (§194)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/audit-pack", "host": [ "{{baseUrl}}" ], "path": [ "audit-pack" ], "variable": [] }, "description": "Returns a catalog of all 16 Audit Packs (12 NPPES specialty supply studies + 4 CMS Care Compare facility studies). Each entry includes the dataset slug, current methodology version, refresh cadence, and direct links to the public web view, the PDF download, and the JSON download. Compliance-tool integrations consume this endpoint to keep their internal Audit Pack catalog in sync." } }, { "name": "Authenticated Audit Pack metadata + per-field provenance map (§194)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/audit-pack/:slug", "host": [ "{{baseUrl}}" ], "path": [ "audit-pack", ":slug" ], "variable": [ { "key": "slug", "value": "" } ] }, "description": "Returns the full Audit Pack JSON envelope (schema_version 1.0) for a single dataset — methodology version, per-field provenance map, reproducibility steps, limitations stack, version history, compliance Q&A. The same shape is downloadable publicly without auth at GET /api/audit-pack/{slug}/json (and as a PDF at GET /api/audit-pack/{slug}/pdf); this v1 endpoint is for compliance-tool integrations that already auth against the API." } } ] }, { "name": "Evidence Query", "description": "Provenance-grounded natural-language Q&A (§197). Ask questions about provider supply; get the answer plus a per-claim evidence trail (source URL, last-checked, methodology version, confidence). The LLM-classifier output is runtime-validated against a strict whitelist enum and never produces SQL — typed dispatchers handle the data lookup.", "item": [ { "name": "Provenance-grounded natural-language Q&A (§197)", "request": { "method": "POST", "url": { "raw": "{{baseUrl}}/evidence-query", "host": [ "{{baseUrl}}" ], "path": [ "evidence-query" ], "variable": [] }, "description": "POST a natural-language question about U.S. healthcare-provider supply data. Returns a 1-2 sentence answer plus a per-claim evidence trail (source URL, last-checked timestamp, methodology version + URL, confidence score, per-claim limitations).\n\n**Pipeline (SQL-injection-safe by construction):**\n1. Pre-flight filters reject prompt-injection signatures, payment/claims questions, predictions, vendor comparisons, and single-provider PII fishing before any LLM call.\n2. Anthropic Sonnet maps the question to a strict whitelist intent (dataset slug + state code + intent kind) via tool-use; the input schema constrains output to the registered enums. Output is then runtime-validated.\n3. A typed resolver dispatches to hand-written, pre-existing data accessors. The classifier output never produces SQL — there is no `query()` call that concatenates LLM output into a query string anywhere in the pipeline.\n4. Per-claim provenance is attached from the audit-pack registry; a second LLM call writes the summary constrained to the resolver's exact numbers, with a deterministic-template fallback.\n\n**County-scope honesty:** NPPES has no public county-of-practice field. Queries scoped to a county return state-level supply with `geo_widened: true` flagged in the answer and an explicit limitation in the evidence trail.\n\n**Refusal codes:** `out_of_scope`, `predictions`, `payment_data`, `competitor_compare`, `individual_provider_lookup`, `prompt_injection`, `classification_failed`. Refusals return HTTP 200 with `status: \"refusal\"` and a machine-readable `refusal.code`.\n\nDemo (no auth, 10 queries / 24h per IP): POST `/api/evidence-query/demo` with the same body shape." } } ] }, { "name": "Exports", "description": "AI-native LLM-ready exports (§198). Pre-chunked text representations of each dataset with inline methodology, source provenance, and citation per chunk. Three formats: NDJSON (streaming), JSON (RAG-ready envelope), text-blocks (paste-into-LLM-prompt-ready). Buyers run their own embedding model + vector store; we provide grounding-ready text + citations.", "item": [ { "name": "AI-native LLM-ready export for a dataset (§198)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/exports/:dataset/llm-ready", "host": [ "{{baseUrl}}" ], "path": [ "exports", ":dataset", "llm-ready" ], "variable": [ { "key": "dataset", "value": "" } ], "query": [ { "key": "format", "value": "", "description": "Output format. Default `json`." } ] }, "description": "Returns the named dataset as pre-chunked text + structured fields + inline methodology + APA citation, in one of three formats:\n\n- `?format=json` (default) — single-document RAG envelope with `dataset`, `narrative`, `chunks[]`, `meta`. Best for batch ingestion where the buyer reads the full payload, indexes the chunks array into a vector DB.\n- `?format=ndjson` — newline-delimited JSON. The first line is a `_dataset_meta` header; subsequent lines are individual chunks. Streaming-friendly; pipe directly into an embedding worker without buffering the full document.\n- `?format=text-blocks` — plain text with `--- METHODOLOGY ---` / `--- CHUNK ---` / `--- CITATION FOOTER ---` delimiters. Designed for direct paste into an LLM prompt for grounded retrieval-free generation.\n\n**Per-chunk shape** (all formats):\n- `id` — stable identifier (e.g. `dermatology-supply:state:CA:v2026.05.0`)\n- `text` — LLM-ready paragraph with provenance baked in\n- `data` — structured fields mirror of the text (state_code, count, density_per_100k, rank, etc.)\n- `methodology` — inline `version`, `source`, `source_url`, `last_checked`, `cadence`, `limitations[]`\n- `citation` — APA-style citation\n- `chunk_type` — `national` | `state` | `underserved` | `dataset_meta`\n\n**Narrative** — a 1-2 paragraph synthetic summary of the dataset, generated via Claude Sonnet on first request and cached per (dataset_slug, methodology_version). Cache hits are free; misses pay the LLM call once per methodology version. Returned as `narrative` in the JSON envelope, in the NDJSON header line, and as a `--- NARRATIVE ---` block in text-blocks.\n\n**Embedding intentionally omitted** — buyers run their own embedding model (OpenAI / Voyage / Cohere) and own their vector storage. This endpoint provides only the grounding-ready text + citations.\n\n**Response headers:** `X-Methodology-Version`, `X-Last-Refreshed`, `X-Total-Chunks`, `X-Narrative-Cache-Hit`." } } ] }, { "name": "NpiEntityResolution", "description": "Cross-dataset entity resolution. Returns the fully joined provider record across NPPES, OIG LEIE, PECOS, QPP MIPS, Open Payments, and SAM.gov, keyed by NPI. Each source block carries a 14-tuple provenance contract (§sprint3-14-tuple-extension). Wave 4Z.6.21 expands this tag with additional paths.", "item": [ { "name": "Cross-dataset entity resolution by NPI", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/npi/:npi", "host": [ "{{baseUrl}}" ], "path": [ "npi", ":npi" ], "variable": [ { "key": "npi", "value": "" } ] }, "description": "Returns the fully joined provider record across NPPES (live), OIG LEIE, PECOS, QPP MIPS, CMS Open Payments (pending ingest), and SAM.gov (pending ingest). Each source block carries a 14-tuple provenance contract (§sprint3-14-tuple-extension).\n\nAnonymous access: 100 req/hour per IP. Authenticated (Bearer key): API-key rate limits.\n\nCaching: 60s fresh, 24h stale-while-revalidate (anonymous only). Wave 4Z.6.21 expands this endpoint." } } ] } ] }