Endpoints — Validation

POST /api/validation/validate-appeal-decision

Request Body

{
  "denial_id": "denial-uuid",
  "denial_reason_code": "FREQ_LIMIT",
  "payer_id": "payer-uuid",
  "proposed_evidence_elements": [
    { "type": "clinical_notes", "present": true },
    { "type": "gaf_assessment", "present": true },
    { "type": "psychiatric_evaluation", "present": false }
  ],
  "precedent_ids": ["prec-uuid-1", "prec-uuid-2"],
  "appeal_narrative": "Patient with GAF score 35 demonstrates ongoing need for IOP-level care..."
}

Response (200 OK)

{
  "validation_status": "warnings",
  "checks_passed": [
    "has_narrative",
    "has_precedents",
    "valid_precedents"
  ],
  "warnings": [
    {
      "check": "narrative_length",
      "message": "Narrative seems short (50+ words recommended)",
      "guidance": "Expand with clinical detail: GAF score, functional impact, evidence integration"
    },
    {
      "check": "precedent_relevance",
      "message": "Some precedents are for different denials (Cigna vs. UHC). Verify relevance.",
      "guidance": "Appeals are strongest when precedents are for same payer/denial type"
    }
  ],
  "errors": [],
  "precedent_confidence_summary": {
    "high_confidence": 1,
    "medium_confidence": 1,
    "stale_precedents": 0
  }
}

PR-U Gates (Validation Checks)

Validation Statuses

• clean — All gates pass, ready to submit
• warnings — Gates pass but recommendations to address
• errors — Gate failures, must fix before submit

---

POST /api/validation/validate-precedent-quality

Validate precedent quality and confidence calibration. Authentication: Required Authorization: Any authenticated user

Request Body

{
  "precedent_ids": ["prec-uuid-1", "prec-uuid-2", "prec-uuid-3"]
}

Response (200 OK)

{
  "validation_status": "clean",
  "precedent_quality_report": [
    {
      "precedent_id": "prec-uuid-1",
      "status": "valid",
      "evidence_score": "Strong",
      "outcome": "Won",
      "confidence_level": "high",
      "warnings": []
    },
    {
      "precedent_id": "prec-uuid-2",
      "status": "valid",
      "evidence_score": "Moderate",
      "outcome": "Won",
      "confidence_level": "medium",
      "warnings": []
    },
    {
      "precedent_id": "prec-uuid-3",
      "status": "stale",
      "evidence_score": "Strong",
      "outcome": "Won",
      "confidence_level": "medium",
      "warnings": [
        "Precedent is 18 months old; payer policies may have changed"
      ]
    }
  ]
}

Precedent Quality Checks

• Evidence Score — Minimal, Moderate, Strong
• Outcome — Won, Lost, Partial, Pending
• Recency — Staleness warning if > 12 months old
• Confidence Level — high (Strong + recent + Won), medium (other combinations), low (Lost outcomes)

---

POST /api/validation/appeal

Comprehensive appeal validation (combines decision + gate validation). Authentication: Required Authorization: Any authenticated user

Request Body

Full appeal object:

{
  "denial_id": "denial-uuid",
  "narrative": "...",
  "evidence_elements": { ... },
  "selected_precedent_ids": [ ... ]
}

Response (200 OK)

Combined validation result:

{
  "validation_status": "warnings",
  "decision_validation": { ... },
  "quality_validation": { ... },
  "recommendations": [
    "Add more recent precedents from 2024",
    "Expand clinical justification section",
    "Consider including collateral contact documentation"
  ]
}

---

POST /api/validation/precedent

Validate precedent before submission to marketplace. Authentication: Required Authorization: admin, biller roles PHI Validation: Request scanned for PHI

Request Body

{
  "precedent_name": "Cigna IOP Appeal Victory",
  "payer": "Cigna",
  "denial_type": "Frequency Limit",
  "loc": "IOP",
  "narrative": "...",
  "evidence_kit": { ... },
  "outcome": "Won",
  "status": "Complete"
}

Response (200 OK)

{
  "validation_status": "clean",
  "checks_passed": [
    "evidence_score_set",
    "outcome_set",
    "policy_reference_complete",
    "denial_trigger_specified",
    "evidence_kit_nonempty"
  ],
  "warnings": [],
  "errors": []
}

PR-U Gates for Precedents

POST /api/validation/export

Request Body

{
  "precedent_ids": ["prec-uuid-1", "prec-uuid-2"],
  "export_format": "json",
  "deidentify": true
}

Response (200 OK)

{
  "validation_status": "warnings",
  "errors": [],
  "warnings": [
    {
      "precedent_id": "prec-uuid-1",
      "check": "outcome_resolution",
      "message": "Outcome still pending — data is incomplete",
      "guidance": "This precedent will be more valuable once appeal resolves"
    }
  ],
  "export_readiness": true
}

PR-D Gates (Export Validation)

Error Responses

Validation Error (422)

{
  "status": "error",
  "type": "validation_failed",
  "message": "Validation failed. Please address errors below.",
  "validation_result": {
    "status": "errors",
    "errors": [
      {
        "check": "has_narrative",
        "message": "Narrative is required",
        "guidance": "Provide 50+ word clinical justification"
      }
    ]
  }
}

Invalid Request (400)

{
  "status": "error",
  "type": "invalid_request",
  "message": "Validation schema error",
  "details": [
    { "path": "precedent_ids", "message": "Expected array" }
  ]
}

See Also