API · v1

GuideTheirCare API

One API for the post-acute transition: facility search, real-time bed availability, transparent cost estimates, and structured discharge workflows. Get an API key and sandbox access at api@guidetheircare.com.

Base URL

https://api.guidetheircare.com/v1

JSON over HTTPS. Versioned path; breaking changes only in new versions.

Authentication

Authorization: Bearer sk_live_…

API keys per environment. Partner scopes (facility:*, hospital:*) granted during onboarding.

Rate limits & PHI

600 req/min per key (search), 60 req/min (writes). PHI-bearing endpoints require a signed BAA; PHI is never logged or retained beyond processing.

Facilities & Search

Public, read-only access to the facility directory — the same data that powers guidetheircare.com/search. Suitable for hospital discharge tools, payer portals, and senior-care advisory products.

GET/v1/facilities

Search facilities. Supports lat/lng + radius, care type, insurance, clinical capabilities, bed availability, and pagination.

GET /v1/facilities?near=39.9489,-75.1577&radius_mi=25&type=LTACH&capabilities=ventilator_weaning&beds_available=true

{
  "data": [
    {
      "id": "fac_keystone-ltach",
      "name": "Keystone Specialty Hospital",
      "type": "LTACH",
      "coordinates": { "lat": 39.9614, "lng": -75.1525 },
      "distance_mi": 1.2,
      "base_price_daily": 1850,
      "beds_available": 3,
      "availability_updated_at": "2026-06-11T14:05:00Z",
      "capabilities": ["ventilator_weaning", "tracheostomy", "dialysis"],
      "insurance_accepted": ["MEDICARE", "MEDICARE_ADVANTAGE", "MEDICAID"]
    }
  ],
  "meta": { "total": 2, "page": 1, "per_page": 25 }
}

GET/v1/facilities/{facility_id}

Full facility profile: description, photos, capabilities, insurance, pricing, and website.

GET/v1/facilities/{facility_id}/availability

Current bed availability with last-verified timestamp. Cheap to poll; webhooks recommended instead.

GET/v1/facilities/{facility_id}/quality

Quality metrics: payroll-based staffing (RN hours, total nurse hours), inspection citations, and CMS rating with provenance fields.

GET/v1/facilities/{facility_id}/reviews

Verified family reviews. Includes verification method per review.

Availability Sync (facility partners)

Write access for facilities and their EHR/census vendors (PointClickCare, MatrixCare) to keep bed availability real-time. Requires the facility:availability scope.

PUT/v1/facilities/{facility_id}/availabilityscope: facility:availability

Set current open beds. Setting beds_available to 0 flips the listing to waitlist.

PUT /v1/facilities/fac_riverbend/availability

// Request
{ "beds_available": 4, "source": "pcc_census_sync" }

// Response 200
{
  "beds_available": 4,
  "has_available_beds": true,
  "availability_updated_at": "2026-06-11T18:22:09Z"
}

GET/v1/facilities/{facility_id}/availability/historyscope: facility:availability

Audit log of availability changes (who, when, via which integration).

Inquiries

Create and manage family-to-facility inquiries. Facilities consume these in the GuideTheirCare partner console or pull them into their own CRM.

POST/v1/inquiries

Submit an inquiry to a facility on behalf of a family. Idempotency-Key header supported.

POST /v1/inquiries

{
  "facility_id": "fac_riverbend",
  "contact": { "name": "Jane Cohen", "email": "jane@example.com", "phone": "+12155550142" },
  "relationship": "daughter",
  "insurance": "MEDICARE_ADVANTAGE",
  "needs": ["orthopedic_rehab", "iv_antibiotics"],
  "discharge_window": "48h",
  "message": "Confirming bed availability for a Friday discharge."
}

GET/v1/inquiriesscope: facility:inquiries

List inquiries for facilities you manage. Filter by status, urgency, and date.

PATCH/v1/inquiries/{inquiry_id}scope: facility:inquiries

Update status (new → contacted → toured → admitted / closed) so conversion analytics stay accurate.

Cost Estimates

The engine behind the cost-transparency calculator: benefit-aware out-of-pocket projections for a given facility, insurance, and length of stay.

POST/v1/cost-estimates

Returns a day-by-day coverage timeline (covered / copay / uncovered segments) plus totals and plan-specific warnings.

POST /v1/cost-estimates

// Request
{
  "facility_id": "fac_riverbend",
  "insurance": "MEDICARE",
  "length_of_stay_days": 30
}

// Response 200
{
  "segments": [
    { "from_day": 1,  "to_day": 20, "daily_oop": 0,   "kind": "covered" },
    { "from_day": 21, "to_day": 30, "daily_oop": 214, "kind": "copay" }
  ],
  "total_out_of_pocket": 2140,
  "warnings": ["Day-21 copay applies; Medigap may cover it."]
}

Clinical Extraction (AI)

Turn unstructured discharge documentation into structured care requirements — the API behind the Care Guide. PHI is processed transiently and never retained; see the BAA addendum.

POST/v1/clinical-extractionscope: clinical:extract

Extract care type, clinical capabilities, and insurance signals from discharge-summary text, with plain-English explanations per finding.

POST /v1/clinical-extraction

// Request
{ "text": "78M ... tracheostomy on hospital day 9, remains ventilator-dependent with daily weaning trials ..." }

// Response 200
{
  "suggested_care_type": "LTACH",
  "capabilities": ["ventilator_weaning", "tracheostomy"],
  "insurance": "MEDICARE_ADVANTAGE",
  "findings": [
    {
      "jargon": "ventilator-dependent with daily weaning trials",
      "plain_english": "Needs help breathing from a machine and a plan to gradually come off it.",
      "capability": "ventilator_weaning"
    }
  ]
}

POST/v1/clinical-extraction/documentsscope: clinical:extract

Async variant for uploaded PDFs/CCDs. Returns a job; result delivered via webhook or polling.

Referrals & Discharge (hospital partners)

For hospital case-management and discharge-planning systems: send a referral packet to multiple facilities at once and track responses — replacing the fax round-robin.

POST/v1/referralsscope: hospital:referrals

Create a referral to one or more facilities, optionally attaching clinical documents by reference.

GET/v1/referrals/{referral_id}scope: hospital:referrals

Referral status across all recipient facilities (received / reviewing / accepted / declined, with reasons).

POST/v1/fhir/DocumentReferencescope: hospital:fhir

FHIR R4 endpoint for attaching discharge documentation (via Kno2 or direct). Consent-gated, consumer-mediated exchange.

GET/v1/fhir/metadata

FHIR CapabilityStatement for the supported R4 surface.

Webhooks

Push notifications for the events that matter. Deliveries are signed (HMAC-SHA256, X-GTC-Signature header) and retried with exponential backoff for 24 hours.

POST/v1/webhooks

Create a subscription. Events: availability.updated, inquiry.created, inquiry.status_changed, referral.response_received, extraction.completed.

Example delivery — availability.updated

{
  "id": "evt_8f4b21",
  "type": "availability.updated",
  "created_at": "2026-06-11T18:22:10Z",
  "data": {
    "facility_id": "fac_riverbend",
    "beds_available": 4,
    "previous_beds_available": 6
  }
}

GET/v1/webhooks

List subscriptions.

DELETE/v1/webhooks/{webhook_id}

Remove a subscription.

Roadmap notes

OAuth 2.0 client-credentials flow for EHR vendors managing many facilities under one integration.
Bulk facility export (NDJSON) for analytics partners, refreshed nightly.
FHIR R4 expansion: ServiceRequest for referrals and Coverage for benefits-checking, aligned with the Kno2 integration.
Expanded sandbox dataset covering additional markets and edge cases (waitlists, bariatric capacity, Medicaid-pending).

Questions or early-access requests: api@guidetheircare.com · or explore the product at /search.