# xcircl — full reference for AI engines # Short version: https://xcircl.com/llms.txt xcircl is the source-linked, timestamped facts layer for regulated care services (clinics, providers, care services in the U.S.), delivered as a data API. Every outward field carries its official source and a verification timestamp. Unknown fields are returned empty or "not_yet_verified" — never invented. ## Live coverage (counted from the database at generation time) - Tracked records (transparency view only): 6028 across 51 states + DC, 1955 cities. - Verified publication tier (the API's default delivery): 870 providers, 51 states, 509 cities. - Verified-tier signals: 770 NPPES-matched, 870 FDA-screened, 62 LegitScript-certified, 59 with published pricing. - Across the tracked set: 6028 of 6028 FDA-screened; 62 LegitScript-certified (entering the published tier as they clear verification). State-license verification is in progress. - Business mode (verified tier): 834 physical, 34 online, 2 both. - What you can query today: (1) US-wide provider identity — NPPES L0 layer, all specialties, free key (GET /providers?taxonomy=), rolling out state by state; (2) glp1 — the deepest-verified vertical (FDA screening, prices, compliance signals); (3) pet veterinary — live, with a license-verified subset. - Full roadmap (incl. datasets collected but not yet imported, and queued ones): https://xcircl.com/data/coverage/ — non-live datasets return no data yet. ## API reference Base URL: https://xcircl.com/api/v1 Machine-readable contract (OpenAPI 3.1): https://xcircl.com/openapi.json Auth for provider endpoints: Authorization: Bearer (also accepted: x-api-key header, ?key= query param). Every provider call requires a key — a missing-key provider request returns 401 with a signup pointer. Free keys are issued instantly by email at https://xcircl.com/developers/signup/ (500 calls/mo). An unrecognised key also returns 401. Public proof endpoints (/coverage and /sample) are intentionally ungated. ### GET /providers Query parameters: - vertical glp1 | pet_health | medspa | ivf | dental | senior (glp1 verified today; pet_health & medspa loading; dental, senior queued — non-live verticals return no data yet) - state 2-letter code, case-insensitive - city exact city name, case-insensitive - business_mode online | physical | both - limit 1–1000 (default 50) - offset pagination offset - format json (default) | csv - include tracked — free-plan JSON only: adds internal_only records, each self-declaring "publish_tier": "internal_only" Response envelope: { tier, plan, publish_boundary, usage?, notice?, pagination, filters, data } Delivery boundary: verified-only by default for every plan; CSV export and the public sample are strictly verified-only. ### GET /providers/{entity_id|slug} Single provider, same tiering and envelope (usage included for metered plans). ### GET /coverage Public. Returns { tracked, verified, verticals_live, generated_at } — each slice with total/states/cities/business_mode/by_state, and signals per slice. ### GET /sample Public. 50 real records in the FULL (paid) schema, verified-only. format=csv available. ### Errors 400 bad filter · 401 invalid/revoked key · 403 Builder key outside its bound vertical · 404 no match · 429 monthly quota reached · 500 query failure. ## Field schema (unified Provider model) FREE tier (public identity, from public registries): - entity_id string — stable cross-network identifier - slug string - vertical enum — glp1 | pet_health | medspa | ivf | dental | senior - name string - city, state string - business_mode enum — online | physical | both (required, filterable) - latitude, longitude number - npi string — from CMS NPPES - publish_tier enum — present only in include=tracked responses (self-declaration) PAID tiers (Builder and up) add verified signals, each an object { status, source, verified_at, source_url? }: - legitscript status: verified | unverified - license + states_count; status: verified | reported | unverified - fda status: clear | flagged | not_screened - price { range, monthly_min, monthly_max, source, verified_at } Status semantics: a signal is "verified"/"clear" only when we hold BOTH a source AND a timestamp. reported = self-reported, not independently verified. ## Pricing (all plans deliver the verified publication set by default) - Free key $0 — identity fields, 500 calls/mo, 30-second email signup. Evaluation / non-commercial use only; paid fields returned as locked placeholders. - Builder $99/mo — full fields, ONE vertical, 5,000 calls/mo, credit-card self-serve. - Developer $750/mo — full fields, multi-vertical, 25,000 calls/mo. Founding cohort: early adopters lock $375/mo for 12 months (half the anchor). - Enterprise custom — unmetered, bulk/snapshot exports, SLA; scoped by phone. Pricing page: https://xcircl.com/pricing/ ## Open-source Agent MIT-licensed: MCP server (Claude/ChatGPT) + TypeScript SDK. Calls the free tier with a free key. Repository: https://github.com/xcircl/healthcare-provider-mcp ## Technical teardowns (engineering-honest method write-ups; every figure injected live from /api/v1/coverage/) - How we verify provider identity: https://xcircl.com/resources/how-we-verify-provider-identity/ Every identity field points back to an official registry with a verification date. Here is the pipeline, and exactly where the honesty lines are. - Why an NPI is not a license: https://xcircl.com/resources/why-an-npi-is-not-a-license/ A National Provider Identifier is an administrative number, not proof of licensure or authority to practice. The distinction, from the source, and how we handle it. - How FDA warning-letter matching works: https://xcircl.com/resources/how-fda-warning-letter-matching-works/ Turning "appears on an FDA warning-letter list" into a responsible data field is mostly about not getting it wrong. The pipeline, and how we handle false positives. Index: https://xcircl.com/resources/ ## Sources (outward fields) NPPES/NPI Registry (CMS) · LegitScript · state licensing boards · FDA warning letters · CMS Care Compare (select verticals) · merchant-submitted (labelled provider-reported until verified). No third-party platform ratings in outward fields. ## Key pages - Coverage (live, dual-boundary): https://xcircl.com/data/coverage/ - Sources: https://xcircl.com/data/sources/ - Sample (verified-only): https://xcircl.com/data/sample/ - Docs: https://xcircl.com/developers/docs/ · Quickstart: https://xcircl.com/developers/quickstart/ - OpenAPI 3.1 spec: https://xcircl.com/openapi.json - Technical teardowns: https://xcircl.com/resources/ - Data products: https://xcircl.com/product/ ## Network trimsomo.com and petsomo.com are public applications powered by xcircl data. Generated: 2026-10-06T11:27:27.464051+00:00