API Reference

Facilities API

Five endpoints cover everything you need about a facility: search, canonical detail, side-by-side compare, predictive risk, and citable evidence.

Search#

List facilities matching geography and quality filters. Supports `zip_code`, `state_code`, `min_safety_score`, `facility_type`, and `license_status`. Use this to drive directory pages, agent shortlists, and underwriting prefilters.

curl -sS "https://api.cribscore.co/v1/facilities?zip_code=90003&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

import httpx

response = httpx.get(
    "https://api.cribscore.co/v1/facilities",
    params={"zip_code": "90003", "limit": 5},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30.0,
)
response.raise_for_status()
payload = response.json()

for facility in payload["data"]:
    print(facility["id"], facility["name"], facility.get("safety_score"))

const params = new URLSearchParams({ zip_code: "90003", limit: "5" });
const response = await fetch(`https://api.cribscore.co/v1/facilities?${params.toString()}`, {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    Accept: "application/json",
  },
});

if (!response.ok) {
  throw new Error(`CribScore search failed: ${response.status}`);
}

const { data } = await response.json();
console.log(data.map((facility: { id: string; name: string }) => facility.name));

{
  "data": [
    {
      "id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
      "name": "Sunrise Learning Center",
      "state_code": "CA",
      "facility_type": "center",
      "license_status": "active",
      "safety_score": 87,
      "source_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/details/198000123"
    }
  ],
  "meta": { "limit": 5, "offset": 0, "total": 41 }
}

Facility detail#

Read a canonical, source-linked record. Includes provider identity, license status, inspections, violations, evidence, score history, and the merge context CribScore used to assemble the record.

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
  "name": "Sunrise Learning Center",
  "state_code": "CA",
  "facility_type": "center",
  "license_status": "active",
  "safety_score": 87,
  "source_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/details/198000123",
  "trust": { "tier": "launch_ready", "explanation": "complete inspection + violation history" },
  "inspections": [
    { "date": "2026-02-18", "violations": 0, "source": "CA CCLD" }
  ]
}

Compare#

Score two or more facilities side-by-side across configurable dimensions. The response includes per-dimension deltas plus a structured recommendation suitable for embedding in a memo.

curl -X POST "https://api.cribscore.co/v1/facilities/compare" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "facility_ids": [
      "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
      "fac_01HZ8X9P5T9Y8B3C5RW2GZK6Q"
    ],
    "dimensions": ["safety_score", "price_weekly", "license_status"]
  }'

{
  "comparison_id": "cmp_01HZ8YA7VBJ4Q3W6PK9NT0DZ2X",
  "dimensions": ["safety_score", "price_weekly", "license_status"],
  "rows": [
    { "facility_id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W", "safety_score": 87, "price_weekly": 340, "license_status": "active" },
    { "facility_id": "fac_01HZ8X9P5T9Y8B3C5RW2GZK6Q", "safety_score": 81, "price_weekly": 320, "license_status": "active" }
  ],
  "summary": "Sunrise leads on safety_score (+6); Maple leads on price_weekly (-$20)."
}

Risk forecast#

Predictive risk surface — `horizon_days` between 7 and 90. Returns a calibrated probability plus the top contributing signals. Use this in monitoring jobs and underwriting reviews.

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W/risk-forecast?horizon_days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "facility_id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
  "horizon_days": 30,
  "risk_probability": 0.12,
  "top_signals": [
    { "signal": "violation_velocity_90d", "weight": 0.34 },
    { "signal": "license_renewal_proximity", "weight": 0.21 }
  ],
  "generated_at": "2026-05-15T08:14:11Z"
}

Evidence#

Citable evidence per facility — inspection PDFs, violation citations, public records — designed for agent grounding and memo generation.

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W/evidence?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "evd_01HZ8YK4X3F8B9T5RC2WN6PHJD",
      "kind": "inspection_report",
      "title": "2026-02-18 Annual Inspection",
      "url": "https://www.ccld.dss.ca.gov/.../198000123/2026-02-18.pdf",
      "summary": "No deficiencies. Ratio + supervision compliant.",
      "captured_at": "2026-02-19T02:14:00Z"
    }
  ],
  "meta": { "limit": 5, "offset": 0, "total": 7 }
}

Endpoint reference#

GET/v1/facilities

Search licensed facilities by geography and quality.

Name	Type	Required	Default	Description
zip_code	string	optional	—	5-digit US ZIP.
state_code	string	optional	—	ISO state code (CA, TX, NY...).
min_safety_score	integer	optional	—	0-100 floor for `safety_score`.
facility_type	string	optional	—	`center` \| `home` \| `school_age`.
license_status	string	optional	—	`active` \| `expired` \| `revoked`.
limit	integer	optional	20	1-100.
offset	integer	optional	0	0+.

Requestbash

curl -sS "https://api.cribscore.co/v1/facilities?zip_code=90003&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Responsejson

{
  "data": [
    {
      "id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
      "name": "Sunrise Learning Center",
      "state_code": "CA",
      "facility_type": "center",
      "license_status": "active",
      "safety_score": 87,
      "source_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/details/198000123"
    }
  ],
  "meta": { "limit": 5, "offset": 0, "total": 41 }
}

GET/v1/facilities/{facility_id}

Canonical, source-linked record for one facility.

Name	Type	Required	Description
facility_id	string	required	ULID returned from search.

Requestbash

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responsejson

{ "id": "...", "name": "...", "source_url": "...", "trust": { "tier": "launch_ready" } }

POST/v1/facilities/compare

Side-by-side compare across configurable dimensions.

Name	Type	Required	Description
facility_ids	string[]	required	2-5 facility IDs.
dimensions	string[]	optional	Dimensions to score; defaults to safety, price, license.

Requestbash

curl -X POST "https://api.cribscore.co/v1/facilities/compare" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "facility_ids": [
      "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
      "fac_01HZ8X9P5T9Y8B3C5RW2GZK6Q"
    ],
    "dimensions": ["safety_score", "price_weekly", "license_status"]
  }'

Responsejson

{ "comparison_id": "...", "rows": [...], "summary": "..." }

GET/v1/facilities/{facility_id}/risk-forecast

Predictive risk probability with top signals.

Name	Type	Required	Default	Description
facility_id	string	required	—	ULID.
horizon_days	integer	optional	30	7-90 days.

Requestbash

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W/risk-forecast?horizon_days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responsejson

{ "risk_probability": 0.12, "top_signals": [...] }

GET/v1/facilities/{facility_id}/evidence

Citable evidence items (inspection PDFs, violations, public records).

Name	Type	Required	Default	Description
facility_id	string	required	—	ULID.
limit	integer	optional	10	1-50.
offset	integer	optional	0	0+.

Requestbash

curl -sS "https://api.cribscore.co/v1/facilities/fac_01HZ8X9K2D7N3M5P0AYR4FTC2W/evidence?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responsejson

{ "data": [...], "meta": { "limit": 5, "offset": 0, "total": 7 } }

Search#

Facility detail#

Compare#

Risk forecast#

Evidence#

Endpoint reference#

Related#