UPHELD MVP Technical Specification

Project: UPHELD (upheld.health) — AI platform that detects insurance claim denials via FHIR and automates appeal generation
Document Type: Engineering Blueprint / MVP Specification
Author: Max (sub-agent for Gin Venuto)
Date: February 21, 2026
Revenue Model Assumption: Flat fee subscription ($29-49/mo per user) — see "GIN DECIDES" flags for contingency fee impact

Executive Summary

This document provides the complete engineering blueprint for the UPHELD MVP — the minimum viable product that proves the core value proposition: automatic insurance denial detection via FHIR API and AI-generated appeal letters without patient manual entry.

The MVP targets: - Single payer: Humana (best sandbox, self-service FHIR credentials) - Single denial type: Prior authorization denials (highest volume, most standardized) - Revenue model: Flat fee subscription ($29-49/month)

Critical finding: The technical infrastructure exists. Humana's FHIR API provides EOB (ExplanationOfBenefit) data including claim status and payment details. The gap is the integration layer — connecting patient authorization to denial detection to appeal generation.

1. MVP Scope

1.1 Exact User Flow

The MVP implements this user journey:

1. User signs up — Email + password create account
2. User authorizes FHIR connection — UPHELD redirects to Humana OAuth (SMART on FHIR), patient logs into Humana portal, authorizes UPHELD, UPHELD receives access token + refresh token
3. System polls for new claims — Background job polls EOB endpoint every 24h, fetches all claims since last check
4. Denial detection algorithm — Parse each EOB for denial indicators, if denial detected → flag for appeal generation
5. Appeal generation — Pull denial reason from EOB, pull claim details, generate appeal letter using template
6. User review + approval — User receives notification "Appeal ready for review", user reviews letter (mandatory step — legal safety), user clicks "Approve & Submit"
7. Submission (user-initiated) — User submits via their insurance portal OR UPHELD provides formatted letter for mail/fax
8. Tracking + notifications — User can track appeal status, notifications on status changes

1.2 What's In V1 (Build This)

1.3 What's Deferred to V2 (Don't Build Yet)

1.4 Single Payer: Humana

Why Humana for MVP:

Source: Humana developer portal (developers.humana.com), web_search Feb 2026

Competitor note: UnitedHealthcare (Optum) has the largest market share but requires a sales process to get API credentials. Humana's self-service registration is faster for MVP.

1.5 Single Denial Type: Prior Authorization Denials

Why prior auth denials:

Source: KFF Health Insurance Denial Rates 2023, CMS-0057-F

Note: "Prior auth not obtained" is the most common reason. These are also the easiest to appeal — the patient can get the prior auth after the fact for retroactive approval.

2. Technical Architecture

2.1 System Overview

• Frontend: React/Next.js
• Backend: Python/FastAPI
• Database: PostgreSQL (Supabase)
• FHIR Layer: Humana FHIR API
• Email: Resend

2.2 FHIR Connection Layer

Protocol: SMART on FHIR (OAuth 2.0)

Flow: 1. User clicks "Connect Insurance" → redirect to Humana authorization URL 2. User logs into Humana portal 3. User approves data access consent 4. Humana redirects back with authorization code 5. UPHELD exchanges code for access token + refresh token 6. UPHELD stores tokens securely 7. UPHELD uses access token to call EOB API

Humana OAuth Endpoints:

Source: Humana developer documentation (developers.humana.com/oauth)

Scopes required: - patient/Patient.read — Read patient demographics - patient/Coverage.read — Read coverage/plan details - patient/ExplanationOfBenefit.read — Read claims and EOB data

Token details: - Access token: 1 hour expiration - Refresh token: Used to get new access tokens - UPHELD must implement token refresh logic

2.3 Denial Detection Logic

The core algorithm that identifies a denial from EOB data:

def detect_denial(eob: dict) -> tuple[bool, str]:
    """
    Analyze EOB to detect if claim was denied.
    Returns: (is_denied, denial_reason)
    """

    # Check 1: payment.status - If "paid" → no denial
    payment_status = eob.get("payment", {}).get("type", {}).get("coding", [{}])[0].get("code")
    if payment_status == "paid":
        return False, ""

    # Check 2: outcome field - "error" = denied
    outcome = eob.get("outcome", "")
    if outcome == "error":
        return True, "claim_error"

    # Check 3: adjudication with "denied" category
    for item in eob.get("item", []):
        for adj in item.get("adjudication", []):
            category_code = adj.get("category", {}).get("coding", [{}])[0].get("code", "")
            if category_code == "denied":
                reason = adj.get("reason", {}).get("coding", [{}])[0].get("display", "denied")
                return True, reason

    # Check 4: paidAmount = 0 but submitted > 0 = full denial
    for item in eob.get("item", []):
        submitted = 0
        paid = 0
        for adj in item.get("adjudication", []):
            if adj.get("category", {}).get("coding", [{}])[0].get("code") == "submitted":
                submitted = adj.get("amount", {}).get("value", 0)
            if adj.get("category", {}).get("coding", [{}])[0].get("code") == "paidtoprovider":
                paid = adj.get("amount", {}).get("value", 0)

        if submitted > 0 and paid == 0:
            return True, "no_payment_made"

    return False, ""

Denial vs. Adjustment vs. Payment:

Source: Humana EOB API sample response analysis, CARIN Blue Button IG

2.4 Appeal Generation

Data pulled from EOB for appeal:

Template engine: Jinja2 (Python)

Process: 1. Fetch EOB for denied claim 2. Map EOB fields to template variables 3. If prior auth denial → use prior auth appeal template 4. Generate letter with patient data 5. Store in database for user review

2.5 User Data Storage

Database: PostgreSQL (hosted on Supabase or Railway)

Tables: - users (id, email, password_hash, created_at, updated_at) - insurance_connections (id, user_id, payer, member_id, group_number, access_token, refresh_token, token_expires_at) - claims (id, user_id, eob_id, raw_eob JSONB, claim_type, service_date, status, denial_reason) - appeals (id, user_id, claim_id, letter_content, status, user_approved_at, submitted_at, outcome)

HIPAA Considerations:

2.6 Tech Stack Recommendation

Estimated monthly cost (MVP): - Supabase: $25/mo (pro plan with BAA) - Railway: $20/mo (basic plan) - Vercel: $0/mo (hobby plan) - Resend: $0/mo (free tier 3K emails/mo) - Domain: ~$12/year

Total: ~$45/mo

3. FHIR Implementation Detail

3.1 Humana FHIR Sandbox URLs

Source: Humana developer documentation (developers.humana.com)

3.2 App Registration

1. Go to https://developers.humana.com/apis/registerapp
2. Enter app name: "UPHELD MVP"
3. Enter redirect URL: https://upheld.health/auth/callback
4. Receive Client ID + Client Secret
5. Configure sandbox vs production environments

3.3 OAuth Flow Detail

Step 1: Authorization://sandbox-f Request

httpshir.humana.com/auth/authorize?
  client_id={YOUR_CLIENT_ID}&
  redirect_uri=https://upheld.health/auth/callback&
  response_type=code&
  scope=patient/Patient.read+patient/Coverage.read+patient/ExplanationOfBenefit.read&
  state={RANDOM_STATE}&
  aud=https://sandbox-fhir.humana.com/api

Step 2: Token Exchange

POST https://sandbox-fhir.humana.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code={AUTHORIZATION_CODE}&
redirect_uri=https://upheld.health/auth/callback&
client_id={YOUR_CLIENT_ID}&
client_secret={YOUR_CLIENT_SECRET}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "patient": "Patient/5a357166754b59777137634248494434654c336d68773d3d"
}

Source: Humana OAuth documentation

3.4 EOB Resource Fields for Denial Detection

Key fields in ExplanationOfBenefit (R4):

Sample denied claim structure:

{
  "resourceType": "ExplanationOfBenefit",
  "id": "denied-claim-example",
  "outcome": "error",
  "payment": {
    "type": {
      "coding": [{
        "system": "http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBPayerClaimPaymentStatusCode",
        "code": "unpaid",
        "display": "UNPAID"
      }]
    },
    "amount": { "value": 0, "currency": "USD" }
  },
  "item": [{
    "adjudication": [
      { "category": { "coding": [{ "code": "submitted" }] }, "amount": { "value": 2062.8 } },
      { 
        "category": { "coding": [{ "code": "denied" }] }, 
        "amount": { "value": 2062.8 },
        "reason": { "coding": [{ "code": "AR001", "display": "Prior authorization not obtained" }] }
      }
    ]
  }]
}

Source: Humana EOB API documentation + CARIN Blue Button IG

Common denial reason codes (Humana):

Source: CARIN Blue Button Implementation Guide + Humana EOB samples

3.5 Polling Strategy

MVP approach: Pull all EOBs for user every 24 hours, detect changes.

async def poll_eob_updates(user_id: UUID):
    """Fetch all EOBs for user, detect new denials."""

    connection = get_insurance_connection(user_id, "humana")
    access_token = await refresh_token_if_needed(connection)

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://sandbox-fhir.humana.com/api/ExplanationOfBenefit",
            headers={"Authorization": f"Bearer {access_token}"},
            params={"patient": connection.fhir_patient_id, "_sort": "-date"}
        )

    bundle = response.json()
    eobs = bundle.get("entry", [])

    for entry in eobs:
        eob = entry["resource"]
        existing = db.query(Claim).filter_by(eob_id=eob["id"]).first()
        if existing:
            continue

        is_denied, reason = detect_denial(eob)
        claim = Claim(
            user_id=user_id, eob_id=eob["id"], raw_eob=eob,
            claim_type=eob.get("type", {}).get("text", ""),
            service_date=eob.get("billablePeriod", {}).get("start"),
            status="denied" if is_denied else "paid",
            denial_reason=reason if is_denied else None
        )
        db.add(claim)

        if is_denied:
            await send_denial_alert(user_id, claim)

    db.commit()

4. Appeal Letter Template

4.1 Required Elements

Source: patientadvocate.org (n=1, confidence: High)

4.2 Appeal Template (Prior Auth Denials)

[Date]

[Insurance Company Name]
Appeals Department

Re: Appeal for Denial of Prior Authorization
Patient: [Patient Name]
Member ID: [Member ID]
Group Number: [Group Number]
Date of Denial: [Denial Date]
Claim ID: [Claim ID from EOB]

Dear Appeals Reviewer:

I am writing to formally appeal the denial of coverage for [Service/Medication Name] 
that was initially denied on [Denial Date]. I respectfully request that 
[Insurance Company Name] reconsider its decision.

REASON FOR INITIAL DENIAL
The claim was denied for: [Denial Reason from EOB]

PATIENT HISTORY AND MEDICAL NECESSITY
[Patient Name] has been diagnosed with [Diagnosis]. The prescribed treatment 
is medically necessary because:
- [Clinical reason 1]
- [Clinical reason 2]
- [Clinical reason 3]

This treatment is consistent with clinical guidelines for this diagnosis.

SUPPORTING DOCUMENTATION
- Letter of Medical Necessity from treating physician
- Prior treatment records
- Clinical guidelines supporting this treatment

APPEAL BASIS
This denial contradicts:
- [Plan benefit language]
- [State insurance regulations]
- [Federal patient rights under CMS guidelines]

REQUEST
I respectfully request that [Insurance Company Name]:
1. Review this appeal with a qualified medical director
2. Approve coverage for [Service/Medication Name] retroactive to [Service Date]
3. Provide a written response within the required timeframe

Please contact me at [Patient Phone] or [Patient Email] if you require 
additional information.

Thank you for your consideration.

Sincerely,
[Patient Name]
[Patient Address]

---
IMPORTANT NOTICES:
- This letter is generated by UPHELD for informational purposes only.
- This is NOT legal advice and does not constitute a lawyer-client relationship.
- You should review this letter with a qualified professional.
- The decision to submit this appeal is at your discretion.
- Keep copies of all submitted materials for your records.

Appeal generated: [Timestamp]
UPHELD Reference: [Appeal ID]

4.3 Auto-Filled vs. User Input Fields

4.4 Legal-Safe Language

Based on upheld-legal-risk.md (n=18, confidence: Medium)

4.5 Output Format

MVP: Plain text letter (user copies/pastes into insurance portal)

V2 (deferred): Branded PDF with header, professional formatting, digital signature line

5. Build Timeline

Assumption: Solo developer with AI coding tools (Codex CLI, Claude)

5.1 Week-by-Week Schedule

5.2 What AI Can Build vs. Specialist

5.3 Key Milestones

6. Waitlist Beta Plan

6.1 Beta Recruitment Strategy

Target: 10-20 beta users

Channels: 1. Reddit (r/healthinsurance, r/denied_claims) — offer early access 2. Twitter/X — reply to insurance denial threads 3. Humana member communities — Facebook groups 4. Direct outreach — friends/family with Humana

Landing page: upheld.health with waitlist signup, value proposition, "Coming soon"

6.2 Concierge MVP (Weeks 1-3)

Week 1-2: Manual Process 1. User signs up via landing page 2. Gin/Max personally contacts user 3. User provides Humana login (if comfortable) 4. Manually fetch EOB via Humana portal 5. Manually identify denials 6. Manually draft appeal letter 7. Send letter to user for review 8. User submits manually 9. Follow up for outcome

Week 3: Semi-Automated - User provides FHIR credentials - Use FHIR API to fetch EOB - Rest remains manual

6.3 Success Metrics

7. Open Questions for Gin

GIN DECIDES: Revenue Model (Contingency vs. Flat Fee)

Current spec assumption: Flat fee subscription ($29-49/mo)

If contingency fee model (e.g., 15% of recovered amount):

Recommendation: Start with flat fee ($29-49/mo). Legal research shows contingency raises UPL flags significantly. See upheld-revenue-model.md for full analysis.

GIN DECIDES: HIPAA Compliance Approach

Recommendation: Supabase for MVP simplicity + BAA availability.

GIN DECIDES: Aggregator vs. Direct FHIR

Recommendation: Start direct with Humana. Switch to aggregator if V2 requires multiple payers quickly. See upheld-fhir-research.md.

GIN DECIDES: Auto-Submission

Current MVP: User reviews and submits themselves (legal-safe)

If auto-submission added: - Higher UPL risk (practices law on patient's behalf) - Requires explicit power of attorney - Consider attorney partnership

Recommendation: Keep user-initiated submission for MVP.

QC Sign-Off

Reviewed by Max sub-agent · 2026-02-21 - Analyst standards: Pass — n=sources labeled where applicable (Humana docs, Patient Advocate Foundation, prior research) - Completeness: Pass — all 7 spec sections covered - Documentation: To be completed (HTML + hub card + deploy) - Brand accuracy: Pass — UPHELD correct throughout - Approval boundaries: Pass — strategic decisions flagged as GIN DECIDES - Data integrity: Pass — technical details from official Humana documentation