Integration Spec — Health Starts at Home

Technical Specification

Platform Integration Architecture

Canary is a module within a healthcare booking platform, not a separate product. It extends existing infrastructure — booking, profiles, payments, messaging — to support environmental health testing.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        HEALTHCARE PLATFORM                          │
│                                                                 │
│  ┌──────────────┐    ┌──────────────────┐    ┌──────────────┐  │
│  │   Booking     │    │  CANARY MODULE   │    │  Provider    │  │
│  │   Engine      │───▶│                  │◄───│  Profiles    │  │
│  │  (existing)   │    │  Nudge Engine    │    │  (extended)  │  │
│  └──────────────┘    │  LMN Workflow    │    └──────────────┘  │
│                      │  Results Router  │                      │
│  ┌──────────────┐    │  Analytics       │    ┌──────────────┐  │
│  │   Patient     │◄───│                  │───▶│  Insurance    │  │
│  │   Messaging   │    └────────┬─────────┘    │  Verification│  │
│  │  (existing)   │             │              │  (existing)  │  │
│  └──────────────┘             │              └──────────────┘  │
└───────────────────────────────┬─────────────────────────────────┘
                               │
                  ┌───────────┬───────────┐
                  │           │           │
            ┌─────┴────┐ ┌───┴───┐ ┌─────┴─────┐
            │ Inspector │ │  Lab  │ │  Truemed   │
            │ Network   │ │ (AIHA)│ │  LMN API   │
            └─────┬────┘ └───┬───┘ └───────────┘
                  │          │
                  └────┬─────┘
                       │
                  ┌────┴────┐
                  │ Results │
                  │ back to │
                  │ Platform│
                  └─────────┘

Every user-facing interaction happens inside the platform. The inspector network, labs, and LMN providers are backend services that the platform orchestrates through the Canary module.

Section 1

Nudge Trigger System

Post-visit nudges that convert existing platform patients into Canary bookings. Uses existing email/push notification infrastructure.

Trigger Conditions

Field	Condition
Appointment specialty	`IN (allergist, pulmonologist, pediatrician, ENT, dermatologist, PCP)`
Appointment status	`completed`
Patient age	>= 18 (or guardian consent = true)
Patient location	Inspector available in zip code

Trigger Timing Config

{
  "nudge_timing": {
    "allergist":      ["post_visit"],
    "pulmonologist":  ["post_visit"],
    "pediatrician":   ["post_booking", "post_visit"],
    "ENT":            ["post_visit"],
    "dermatologist":  ["post_visit"],
    "PCP":            ["post_visit"]
  }
}

A/B Test Framework

Dimension	Variants
Message copy	Specialty-specific vs. generic
Timing	Post-booking vs. post-visit vs. both
CTA	"Book a test" vs. "Learn more" vs. "Check if your home qualifies"
HSA mention	With HSA savings callout vs. without

Variants assigned at patient level for consistent experience. Results tracked via the existing experimentation platform.

Suppression Rules

Rule	Condition
Already booked	Patient has CanaryInspection with status IN (booked, completed, in_progress)
Recent nudge	Last nudge was < 90 days ago
Opted out	Patient opted out of Canary notifications
No coverage	No inspector available within 25 miles of patient zip

Section 2

Provider Profile Extension

One new provider type — environmental_inspector — added alongside MD, DO, NP, PA, DDS in the existing provider enum.

Profile Schema

{
  "provider_type": "environmental_inspector",
  "name": "string",
  "company": "string",
  "certifications": [
    {
      "type": "CIH | ACAC | CMC | CIEC | state_license",
      "number": "string",
      "issuing_body": "string",
      "expiration": "date",
      "verified": "boolean"
    }
  ],
  "services": ["mold_iaq", "water_quality", "allergen_mapping", "comprehensive"],
  "lab_partners": ["EMSL", "Eurofins"],
  "service_area": { "zip_codes": ["string"], "radius_miles": 25 },
  "pricing": {
    "mold_iaq":        { "min": 400, "max": 800 },
    "water_quality":   { "min": 200, "max": 500 },
    "allergen_mapping": { "min": 500, "max": 900 },
    "comprehensive":   { "min": 800, "max": 1500 }
  },
  "rating": "float",
  "review_count": "integer",
  "no_remediation_badge": true
}

Credential Verification Sources

Registry	API / Method	Certifications
ABIH	Roster lookup	CIH
ACAC	Directory scrape	ACAC, CIEC, CMC
NY Dept of Labor	NY DOL API	NY mold assessor/remediator
TX TDLR	TX TDLR API	TX mold assessment
FL DBPR	FL DBPR lookup	FL mold assessor

Re-verification monthly via cron. Expired credentials trigger profile suspension.

Onboarding Flow

Application with credentials

Inspector submits certification numbers, insurance, service area.

Automated credential verification

Pull from ABIH, ACAC, state registries. Pass/fail in < 24 hours.

Background check

Via the existing background check vendor.

Sample report review

Manual review by Canary ops team. Must include clinical correlation section.

Profile published

Inspector appears in Canary search results.

Section 3

Booking Flow Extension

Uses the existing booking engine and calendar integration. Adds test type selection and clinical context passing.

Test Types

Test Type	Description	Duration	Price Range
Mold / IAQ	Air + surface sampling, moisture mapping	2-3 hrs	$400–800
Water Quality	Lead, bacteria, VOCs, PFAS	1 hr	$200–500
Allergen Mapping	Dust mites, pet dander, pollen infiltration	2 hrs	$500–900
Comprehensive	All of the above	3-4 hrs	$800–1,500

Clinical Context (Passed to Inspector)

{
  "referral_context": {
    "referring_specialty": "allergist",
    "diagnosis_category": "allergic_rhinitis",
    "requested_scope": "mold_iaq",
    "patient_notes": "Mold sensitivity confirmed via skin prick test"
  }
}

Opt-in by patient: “Share my visit context with the inspector for a more targeted test.”

Payment

Standard Payment

Existing platform payment rails (Stripe). 25% deposit at booking, balance on inspection day.

HSA/FSA Payment

Toggle at checkout. If selected, triggers LMN workflow (Section 4). ~30% savings for patient.

Section 4

LMN Automation Workflow

Letter of Medical Necessity unlocks HSA/FSA payments. 5-field questionnaire, async physician review, same-day turnaround.

Patient Health Questionnaire (5 fields, < 2 min)

Field	Type	Required
Primary diagnosis	ICD-10 search/select	Yes
Symptoms	Multi-select (wheeze, cough, skin irritation, headache, fatigue, congestion)	Yes
Current medications	Free text	No
Home type	Select (apartment, house, condo, townhouse) + age range	Yes
Reason for testing	Select (physician recommended, self-initiated, landlord dispute, real estate)	Yes

Workflow

Patient opts into HSA payment

Toggle at checkout triggers LMN flow.

Health questionnaire (5 fields)

Diagnosis, symptoms, medications, home type, reason.

LMN review queue

Internal MD/DO/NP/PA reviews async (avg 15 min) — OR — Truemed API (avg 4 hr).

LMN signed with ICD-10 code

Stored in patient profile. HSA/FSA card charged.

API: Request LMN

POST /api/v1/canary/lmn/request
Content-Type: application/json
Authorization: Bearer {platform_internal_token}

// Request body
{
  "patient_id": "uuid",
  "diagnosis_icd10": "J30.1",
  "test_type": "mold_iaq",
  "questionnaire_responses": {
    "symptoms": ["wheeze", "congestion", "headache"],
    "medications": "Flonase, Zyrtec",
    "home_type": "apartment",
    "home_age": "pre_1980",
    "reason": "physician_recommended"
  }
}

API: LMN Response

// Response
{
  "lmn_id": "uuid",
  "status": "pending | approved | denied",
  "signed_date": "2026-04-04T14:30:00Z",
  "provider_name": "Dr. Sarah Chen, MD",
  "provider_npi": "1234567890",
  "document_url": "/api/v1/canary/lmn/{lmn_id}/document",
  "icd10_codes": ["J30.1", "J45.20"],
  "expiration_date": "2027-04-04"
}

Section 5

Results Delivery

Inspector uploads report. Patient and referring physician both receive structured results through existing platform messaging.

API: Upload Report

POST /api/v1/canary/inspections/{inspection_id}/report
Content-Type: multipart/form-data

Fields:
  report_pdf:          file    (full report)
  findings_summary:    json    (structured findings)
  contaminant_levels:  json    (key-value with units + thresholds)
  clinical_correlation: text   (inspector's clinical relevance notes)
  photos:              file[]  (minimum 20)

Structured Findings Schema

{
  "findings": [
    {
      "contaminant": "Stachybotrys chartarum",
      "level": 1200,
      "unit": "spores/m3",
      "threshold": 500,
      "location": "Bathroom ceiling",
      "severity": "elevated",
      "clinical_relevance": "Associated with allergic rhinitis symptoms"
    }
  ],
  "overall_risk": "moderate",
  "remediation_recommended": true,
  "remediation_scope": "Bathroom mold removal, HVAC cleaning"
}

Delivery Routes

Recipient	Channel	Content
Patient	Secure messaging + email	Full report PDF + plain-language summary
Referring physician	Provider messaging	Clinical summary (findings, levels, correlation)
Patient (follow-up)	Booking prompt	“Discuss your Canary results with Dr. [name]”
Patient (if remediation)	Platform notification	Remediation referral with vetted partners

Section 6

Data Model

Four new entities. Standard relational model. Plugs into existing patient and appointment tables.

Entity Relationship Diagram

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│   Patient    │     │ CanaryInspection │     │  CanaryReport  │
│  (existing)  │────▶│                  │────▶│               │
└─────────────┘     │  inspection_id  │     │  report_id     │
       │            │  patient_id     │     │  inspection_id │
       │            │  inspector_id   │     │  findings[]    │
       │            │  test_type      │     │  overall_risk  │
       │            │  booking_id     │     │  report_url    │
       │            │  status         │     └───────────────┘
       │            └──────────────────┘
       │                     │
       │            ┌───────┴──────────┐
       │            │CanaryRemediation  │
┌─────┴───────┐│                  │
│  CanaryLMN  ││  remediation_id  │
│             ││  inspection_id   │
│  lmn_id     ││  partner_id      │
│  patient_id ││  scope           │
│  status     ││  status          │
│  icd10[]    ││  clearance_id    │
│  signed_by  │└──────────────────┘
│  doc_url    │
└─────────────┘

Entity Definitions

Entity	Key Fields	Relationships
CanaryInspection	inspection_id, patient_id, inspector_id, test_type, status, referral_context, nudge_id	Patient, Appointment, Inspector, CanaryReport
CanaryReport	report_id, inspection_id, findings[], contaminant_levels[], overall_risk	CanaryInspection
CanaryLMN	lmn_id, patient_id, status, icd10_codes[], signed_by, document_url, expires_at	Patient, CanaryInspection
CanaryRemediation	remediation_id, inspection_id, partner_id, scope, status, clearance_inspection_id	CanaryInspection (original + clearance)

Analytics Events

Event	Trigger	Key Properties
`nudge_shown`	Nudge rendered	specialty, timing, variant_id
`nudge_clicked`	Patient clicks CTA	specialty, timing, variant_id
`booking_started`	Enters booking flow	test_type, source (nudge vs. organic)
`booking_completed`	Confirms booking	test_type, payment_method, inspector_id
`hsa_opted_in`	Selects HSA/FSA	test_type, price
`lmn_requested`	LMN workflow triggered	icd10, route (internal vs. truemed)
`lmn_signed`	LMN approved	turnaround_minutes, provider_npi
`report_delivered`	Report sent to patient	overall_risk, contaminant_count
`physician_notified`	Summary sent to doc	referring_specialty
`followup_booked`	Follow-up booked	days_since_report
`remediation_referred`	Remediation referral	scope, estimated_cost

Section 7

Implementation Phases

Four phases over six months. Phase 0 validates demand with zero backend work.

Phase 0 — Fake Door Test

Validate demand. 2 weeks. Zero backend.

Banner on post-visit confirmation for target specialties: “Concerned about mold, allergens, or air quality at home? Environmental testing coming soon.” CTA collects email. Measure click-through rate, signups, specialty breakdown.

Engineer

Sprint

2 wk

Calendar

Phase 1 — Manual MVP

First real bookings. End-to-end flow with manual steps.

New provider type (environmental_inspector), inspector profiles with credential display, basic booking flow (test type + calendar + payment), clinical context field, manual LMN process, report delivery via secure messaging.

Engineers

Sprints

2 mo

Calendar

Phase 2 — Nudge Automation

Automated patient acquisition from the existing booking flow.

Nudge trigger system, A/B testing framework for copy/timing/CTA, suppression rules, conversion tracking (nudge to booking to completion).

Engineer

Sprints

1 mo

Calendar

Phase 3 — HSA + LMN + Results

Full financial and clinical integration.

HSA/FSA payment toggle, automated health questionnaire, LMN review queue (internal or Truemed API), structured report parsing, clinical summary delivery to referring physician, follow-up booking prompt.

Engineers

Sprints

2 mo

Calendar

Phase 4 — Data Layer + Expansion

Unlock network effects and scale.

Analytics dashboard, anonymized environmental health dataset by zip code, predictive nudges, insurance partnership data package, expansion playbook for new metros.

Section 8

Estimated Engineering Effort

Phase	Engineers	Sprints	Calendar	Scope
Phase 0	1	1	2 weeks	Static banner, email capture
Phase 1	2	4	2 months	New provider type + booking extension
Phase 2	1	2	1 month	Nudge logic + A/B framework
Phase 3	2	4	2 months	HSA + LMN + results delivery
Total	2 avg	11	~6 months	Full Canary module

What the Platform Already Has (Zero Build)

Patient accounts and profiles
Provider search and discovery
Appointment booking and calendar
Payment processing (Stripe)
Email and push notifications
Secure messaging (patient-provider)
Insurance verification infrastructure
A/B testing platform
Mobile apps (iOS, Android)

What Canary Adds

1 new provider type
1 new booking sub-flow
1 new notification type
1 new workflow (LMN)
1 new upload flow (reports)
4 new database entities
11 new analytics events

This is not a platform build. It is a feature extension.

API Endpoints Summary

Method	Endpoint	Description
`POST`	`/api/v1/canary/lmn/request`	Request a Letter of Medical Necessity
`GET`	`/api/v1/canary/lmn/{lmn_id}`	Get LMN status and document
`POST`	`/api/v1/canary/inspections/{id}/report`	Inspector uploads report
`GET`	`/api/v1/canary/inspections/{id}/report`	Get inspection report
`GET`	`/api/v1/canary/inspectors`	Search available inspectors
`POST`	`/api/v1/canary/nudge/suppress`	Suppress nudges for a patient
`GET`	`/api/v1/canary/analytics/funnel`	Conversion funnel metrics

See the pilot plan → Revenue model →