Developers · reference

API documentation

A small, predictable REST API over the verified facts layer. Base URL: https://xcircl.com/api/v1. Responses are JSON by default; pass format=csv for a download.

Authentication

Public endpoints (coverage, sample) need no key. The provider endpoints work without a key at the free tier; pass a key to unlock the paid tier. See pricing.

auth

# Pass your key as a Bearer token
curl https://xcircl.com/api/v1/providers/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# x-api-key header and ?key= are also accepted

List providers

Filter by vertical, state, city, business_mode. Page with limit (≤1000) and offset.

request

GET /api/v1/providers/?vertical=glp1&state=CA&business_mode=online&limit=20&offset=0

# format=csv for a CSV download (column set follows your tier)

response (paid tier)

{
  "tier": "paid",
  "pagination": { "total": 6028, "limit": 20, "offset": 0, "returned": 20 },
  "filters": { "vertical": "glp1", "state": "CA", "city": null, "business_mode": "online" },
  "data": [
    {
      "entity_id": "glp1_…",
      "slug": "…",
      "vertical": "glp1",
      "name": "Example Weight Care",
      "city": "Los Angeles",
      "state": "CA",
      "business_mode": "online",
      "latitude": 34.05, "longitude": -118.24,
      "npi": "1234567890",
      "legitscript": { "status": "unverified", "source": null, "verified_at": null },
      "license":    { "status": "reported", "states_count": 3, "source": "Provider-reported", "verified_at": "2026-05-01T…" },
      "fda":        { "status": "clear", "source": "FDA Warning Letters database", "verified_at": "2026-06-01T…" },
      "price":      { "range": "$200–$400/mo", "monthly_min": 200, "monthly_max": 400, "source": "…", "verified_at": "…" }
    }
  ]
}

Single provider

Look up one provider by entity_id or slug. Same tiering as the list.

request

GET /api/v1/providers/{entity_id-or-slug}/

Coverage

Public aggregate — counts, business-mode split, and a per-state breakdown, computed live.

request

GET /api/v1/coverage/   # public — live counts, by_state breakdown

Fields & tiers

Free returns public identity. Paid adds verified compliance signals and price — each as an object with status, source, and verified_at.

Field	Type	Tier	Description
`entity_id`	string	free	Stable cross-SoMo identifier.
`name`	string	free	Provider name.
`vertical`	enum	free	glp1 · pet_health · …
`city / state`	string	free	Location.
`business_mode`	enum	free	online · physical · both.
`latitude / longitude`	number	free	Geocoordinates.
`npi`	string	free	NPI from NPPES.
`legitscript`	signal	paid	Certification status + source + date.
`license`	signal	paid	State licensing + states_count + source + date.
`fda`	signal	paid	Warning-letter screen + source + date.
`price`	object	paid	Monthly range + source + date.

Errors

400 — bad filter (unknown vertical / business_mode).
404 — no active provider matches.
500 — query failure.

An unrecognised key never errors — it falls back to the free tier with a notice in the body.

Try it now

Run your first call in five minutes with the quickstart.

Get API key Talk to sales