SNF Citations Spine API

Status: Documentation complete for sales and integration planning. Public API surface is provisioned per customer — not a free public endpoint.

Placeholder: All examples use {BASE_URL}. Replace with the host we send you after onboarding.

Data: National CMS nursing home health citations + SOD narrative join (see product page snapshot). Not ALF. Not Five-Star.

Authentication

API keys are bound to an organization and tier. Send the key on every request:

Bearer header

Authorization: Bearer {API_KEY}

Alternate header (same key)

X-Api-Key: {API_KEY}

Keys can be rotated or revoked without changing your commercial tier.
Tier controls rate limits, geography allow-lists (Explorer), and export features.
Never commit keys to public repos; use secrets stores in CI.

Base URL

Path prefix

{BASE_URL}/v1

Illustrative host (not live)

https://{your-workspace}.cloud.davvv.net/snf/v1

Tier limits (planned defaults)

Tier	Req / min	Notes
Explorer	~60	Limited geography / search; low daily row cap
Builder	~300	Full national spine
Platform	~1,000+	Multi-key; higher concurrency
Enterprise	Custom	Contracted

Exceeded limits return 429 with Retry-After when applicable.

Common response envelope

Success

{
  "data": [ /* resource objects */ ],
  "meta": {
    "request_id": "req_…",
    "tier": "builder",
    "batch": { "label": "2026-07-production", "cms_processing_date": "2026-06-01", "as_of_survey_date": "2026-05-20" },
    "page": { "next_cursor": "…", "limit": 100 }
  }
}

Error

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable detail",
    "request_id": "req_…"
  }
}

Endpoints

Method	Path	Description
`GET`	`/v1/health`	Liveness for your provisioned host
`GET`	`/v1/me`	Org, tier, remaining limits
`GET`	`/v1/coverage`	Batch id, as-of survey date, source versions (PDC + SOD) — not ALF A/B/F levels

Facilities

Method	Path	Description
`GET`	`/v1/facilities`	List / search providers
`GET`	`/v1/facilities/{ccn}`	Single facility by CCN

Query params: state, ccn, q (name), chain, limit, cursor.

Citations

Method	Path	Description
`GET`	`/v1/citations`	Health citation rows (primary grain)
`GET`	`/v1/citations/{id}`	Single citation

Query params: state, ccn, survey_date_from, survey_date_to, tag, scope_severity, ij, standard, complaint, open_like, limit, cursor.

Survey events & tags

Method	Path	Description
`GET`	`/v1/survey-events`	Distinct CCN × survey date rollups
`GET`	`/v1/tags`	F-tag / category dictionary from loaded tags
`GET`	`/v1/scope-severity`	A–L reference + internal RiskWeight

Narratives (tier-gated)

Method	Path	Description
`GET`	`/v1/citations/{id}/narrative`	SOD / 2567 text for a citation (source-attributed)

Bulk export (Platform+)

Method	Path	Description
`POST`	`/v1/exports`	Request a scoped export job
`GET`	`/v1/exports/{id}`	Job status / download handle

Examples

Batch / coverage meta

curl -sS "{BASE_URL}/v1/coverage" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Citations in R12-style window for a state

curl -sS "{BASE_URL}/v1/citations?state=MN&survey_date_from=2025-05-21&survey_date_to=2026-05-20&limit=100" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Immediate Jeopardy only

curl -sS "{BASE_URL}/v1/citations?ij=true&limit=50" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Batch honesty

Always read /v1/coverage (or response meta.batch) before comparing periods.
R12 on the analytics board uses max survey date in the load — not wall-clock “today.”
open_like maps multi-value CMS correction language; it is not a CMS field named Open.
Do not treat internal RiskWeight as CMS Five-Star Health Inspection scoring.

Changelog

Date	Notes
2026-07-29	Initial public contract for SNF Citations Spine (docs-only; provisioned access later). Snapshot figures from July 2026 production load of CMS national extract (processing date 1 Jun 2026).

Docs