← Back to Index

Carmee Pathway API - Full Specification

Version: 1.0
Date: 2026-02-18
Purpose: Automate 60-70% of Carmee's pathway coordination work (10-18 hrs/week savings)
Expected ROI: ~10,000x (API costs <$50/month, saves ~$3,000/month in Carmee time)

Overview

What it does:

What it DOESN'T do:

Integration points:

API Endpoints

1. POST /api/pathway/classify

Purpose: Determine which ZTAG pathway applies to an inquiry

Request:

{
  "inquiry_text": "We're a YMCA after-school program serving 200 kids...",
  "organization_name": "YMCA of Greater Los Angeles",
  "website": "https://ymcala.org",
  "email_domain": "ymcala.org",
  "contact_name": "Jane Smith",
  "contact_email": "jane@ymcala.org"
}

Response:

{
  "pathway_id": 2,
  "pathway_name": "3rd-Party Nonprofit",
  "confidence": 0.95,
  "reasoning": "Organization is 501(c)(3) nonprofit providing supervised after-school programming",
  "next_steps": [
    "Verify 501(c)(3) status (EIN required)",
    "Confirm supervision model (no drop-off/rental)",
    "Check if program is in-school or off-site"
  ],
  "flags": [],
  "estimated_pricing_tier": "EDU (if supervised + in-school) or Professional + 10%"
}

Pathways (1-7):

  1. Grant-Funded School District → EDU pricing
  2. 3rd-Party Nonprofit → EDU (if 501(c)(3) + supervised + in-school) else Professional + 10%
  3. City/Municipal Parks & Rec → EDU (pending confirmation)
  4. Camps (Summer, day camps) → Professional pricing
  5. Operator Partnership (FECs, mobile operators) → Professional pricing, revenue share models
  6. Pilot Program (tryouts, demos) → Professional pricing, potential conversion to Pathway 1-3
  7. Professional/Commercial Operators → Professional pricing

Stop conditions (auto-reject, don't waste time):

Implementation:

2. POST /api/pathway/verify-eligibility

Purpose: Verify 501(c)(3) status, supervision model, website legitimacy

Request:

{
  "organization_name": "YMCA of Greater Los Angeles",
  "ein": "95-1684064",
  "website": "https://ymcala.org",
  "program_description": "Supervised after-school program with Playmakers leading activities"
}

Response:

{
  "nonprofit_status": {
    "is_501c3": true,
    "ein": "95-1684064",
    "organization_name": "YMCA OF GREATER LOS ANGELES",
    "source": "IRS Tax Exempt Organization Search",
    "verified_at": "2026-02-18T14:30:00Z"
  },
  "supervision_check": {
    "is_supervised": true,
    "confidence": 0.9,
    "keywords_found": ["supervised", "Playmakers", "after-school program"],
    "red_flags": []
  },
  "website_check": {
    "is_legitimate": true,
    "organization_type": "nonprofit",
    "mission_statement": "To put Christian principles into practice through programs that build healthy spirit, mind, and body for all.",
    "educational_mission": true
  },
  "eligibility_verdict": "APPROVED for EDU pricing (Pathway 2: 501(c)(3) + supervised + educational mission)",
  "flags": []
}

APIs used:

Red flags (escalate to Carmee):

3. POST /api/pathway/generate-quote

Purpose: Calculate pricing, apply discounts, generate quote PDF

Request:

{
  "pathway_id": 2,
  "buyer_type": "nonprofit_501c3_supervised",
  "products": [
    {"sku": "ZTAGGER_V3", "quantity": 50},
    {"sku": "ZUES_ROUTER", "quantity": 2},
    {"sku": "EXTENDED_CARE_12MO", "quantity": 50}
  ],
  "organization_name": "YMCA of Greater Los Angeles",
  "contact_name": "Jane Smith",
  "contact_email": "jane@ymcala.org",
  "notes": "Grant-funded ELOP program, delivery by March 15"
}

Response:

{
  "quote_id": "Q-2026-02-18-001",
  "pricing_tier": "EDU",
  "line_items": [
    {
      "sku": "ZTAGGER_V3",
      "description": "ZTAGGER v3 Wearable",
      "quantity": 50,
      "unit_price_edu": 149.00,
      "unit_price_msrp": 199.00,
      "discount_percent": 25,
      "subtotal": 7450.00
    },
    {
      "sku": "ZUES_ROUTER",
      "description": "ZUES Control System",
      "quantity": 2,
      "unit_price_edu": 899.00,
      "unit_price_msrp": 1199.00,
      "discount_percent": 25,
      "subtotal": 1798.00
    },
    {
      "sku": "EXTENDED_CARE_12MO",
      "description": "Extended Care 12-Month Subscription",
      "quantity": 50,
      "unit_price_edu": 49.00,
      "unit_price_msrp": 69.00,
      "discount_percent": 29,
      "subtotal": 2450.00
    }
  ],
  "subtotal": 11698.00,
  "bulk_discount": 0,
  "bulk_discount_percent": 0,
  "tax": 0,
  "shipping": "TBD",
  "total": 11698.00,
  "quote_pdf_url": "https://ztag.com/quotes/Q-2026-02-18-001.pdf",
  "valid_until": "2026-03-18",
  "payment_terms": "Net 30 (PO required for government/nonprofit)",
  "notes": "Grant-funded ELOP program, delivery by March 15"
}

Pricing tiers:

Bulk discounts (apply AFTER edu/pro discount):

Output formats:

Implementation:

4. POST /api/pathway/customize-funding-packet

Purpose: Fill in funding proposal templates (ESSER, ELOP, Title funds)

Request:

{
  "grant_type": "ELOP",
  "district_name": "Los Angeles Unified School District",
  "contact_name": "Dr. Sarah Johnson",
  "contact_title": "After-School Programs Director",
  "contact_email": "sjohnson@lausd.net",
  "quantities": {
    "students_served": 500,
    "sites": 5,
    "ztagger_units": 125,
    "zues_systems": 5
  },
  "timeline": "March 2026 - June 2027",
  "budget_amount": 35000
}

Response:

{
  "packet_id": "FP-ELOP-LAUSD-2026-02-18",
  "template_used": "ELOP Funding Proposal v2.3",
  "sections_generated": [
    "Executive Summary",
    "Program Description",
    "Alignment with ELOP Goals",
    "Budget Justification",
    "Implementation Timeline",
    "Outcomes & Evaluation"
  ],
  "pdf_url": "https://ztag.com/funding-packets/FP-ELOP-LAUSD-2026-02-18.pdf",
  "word_doc_url": "https://ztag.com/funding-packets/FP-ELOP-LAUSD-2026-02-18.docx",
  "draft_email": {
    "subject": "ZTAG Funding Proposal for LAUSD ELOP Program",
    "body": "Hi Dr. Johnson,\n\nAttached is a customized funding proposal for integrating ZTAG into your ELOP program across 5 sites serving 500 students.\n\nKey highlights:\n- Aligns with ELOP goals (SEL, physical activity, inclusive play)\n- $35,000 budget (125 ZTAGGERs + 5 ZUES systems + Extended Care)\n- 16-month implementation (March 2026 - June 2027)\n- Built-in outcomes tracking (participation, engagement, social connections)\n\nHappy to discuss next steps or answer any questions.\n\nBest,\nCarmee"
  },
  "customization_notes": "Pre-filled all quantities, pricing, timeline. Review budget justification for district-specific language."
}

Grant types supported:

Template library location: reference/funding-templates/

Implementation:

5. POST /api/pathway/generate-vp-battle-kit

Purpose: Create pathway-specific value proposition one-pager (VP Battle Kit)

Request:

{
  "pathway_id": 2,
  "buyer_persona": "nonprofit_afterschool_director",
  "pain_points": [
    "Limited budget for programming",
    "Need inclusive activities (all abilities)",
    "Want measurable SEL outcomes"
  ],
  "competitor_context": "Currently using traditional sports equipment, no tech integration"
}

Response:

{
  "battle_kit_id": "VPK-P2-NP-2026-02-18",
  "pathway_name": "3rd-Party Nonprofit",
  "persona": "After-School Program Director (Nonprofit)",
  "key_talking_points": [
    "EDU pricing (25% off) because you're 501(c)(3) + supervised",
    "Inclusive by design - every kid plays, regardless of ability",
    "Built-in SEL outcomes tracking (CASEL framework alignment)",
    "Grant-friendly language (ELOP, ESSER, Title funds)",
    "Proven with 100+ nonprofit partners (YMCAs, Boys & Girls Clubs)"
  ],
  "competitive_advantages": [
    "Unlike traditional sports: No skill barriers, everyone included",
    "Unlike screen-based ed-tech: Embodied play, social connection",
    "Unlike playground equipment: Dynamic games, data-driven insights"
  ],
  "objection_handling": [
    {
      "objection": "Budget too tight for new equipment",
      "response": "EDU pricing + grant funding options. We can help with ELOP/ESSER language. $149/kid for full year with Extended Care."
    },
    {
      "objection": "Staff training burden",
      "response": "2-hour Playmaker training. Simple setup. Kids learn in 5 minutes. Steve (our trainer) supports remotely."
    }
  ],
  "case_studies": [
    "YMCA of Silicon Valley: 80% participation increase, 95% inclusive play rating",
    "Boys & Girls Clubs of America: 12 clubs, 2,000 kids, SEL growth tracked"
  ],
  "pdf_url": "https://ztag.com/battle-kits/VPK-P2-NP-2026-02-18.pdf",
  "one_pager": true
}

Pathways covered: All 7 (each has unique value prop, objections, case studies)

Use cases:

System Integration

Zoho CRM Integration

Read from Zoho:

Write to Zoho:

API access needed:

Email Integration

Inbound parsing:

Outbound drafting:

IRS API (501(c)(3) Verification)

Endpoint: https://apps.irs.gov/app/eos/

Access: Public, no API key required

Query: Organization name or EIN → Returns 501(c)(3) status

Implementation Plan (3 Phases)

Phase 1: Core Classification & Quotes (Week 1-2)

Build:

  1. POST /api/pathway/classify (Gemini Flash classification)
  2. POST /api/pathway/generate-quote (pricing + PDF generation)
  3. Simple web UI for Carmee (paste inquiry → get classification + quote)

Test:

Deploy:

Success metrics:

Phase 2: Eligibility Verification + Funding Packets (Week 3-4)

Build:

  1. POST /api/pathway/verify-eligibility (IRS API + web scraping)
  2. POST /api/pathway/customize-funding-packet (template fill-in)
  3. Zoho CRM read integration (pull deal data)

Test:

Deploy:

Success metrics:

Phase 3: VP Battle Kits + Full Zoho Write (Week 5-6)

Build:

  1. POST /api/pathway/generate-vp-battle-kit (pathway-specific value props)
  2. Zoho CRM write integration (log activity, attach docs, update stages)
  3. Email draft generation (auto-compose responses for Carmee review)

Test:

Deploy:

Success metrics:

Success Metrics (90 Days)

Efficiency:

Business impact:

Cost:

Qualitative:

Technical Stack

Backend:

Frontend (Carmee UI):

Storage:

Hosting:

Security & Privacy

Data handling:

Access control:

Compliance:

Open Questions

Pricing data:

Templates:

Workflow:

Zoho access:

Next Steps

For Quan (Dev work today):

  1. Build Phase 1: Classification + Quote generation
    • POST /api/pathway/classify
    • POST /api/pathway/generate-quote
    • Simple web UI for Carmee testing
  2. Test with real inquiries (10 from past 30 days)
  3. Deploy internally (Carmee validates accuracy)

For Carmee (after Phase 1 ready):

  1. Test API with 10 real inquiries
  2. Validate classification accuracy
  3. Review quote quality (compare to manual quotes)
  4. Provide feedback on UI/UX

For Minnie (documentation + integration):

  1. Document API usage patterns
  2. Monitor API costs (Gemini Flash usage)
  3. Track time savings (Carmee self-reported)
  4. Prepare Zoho integration (Phase 2)

Status: Ready to build. Spec complete. Awaiting Quan's dev session.

Estimated build time:

First priority: Phase 1 (classification + quotes) → Immediate 3-6 hrs/week savings for Carmee

File: plans/carmee-pathway-api-spec.md
Created: 2026-02-18
Based on: Feb 16 pathway automation assessment + Feb 17 pathways governance doc