MarketingTool/docs/AI_OPPORTUNITY_ASSESSMENT.md

Evidence-grounded AI opportunity assessment

Route and safety boundary

POST /api/v1/businesses/{business_id}/ai/opportunity-assessment

The URL ID is an explicit operator selection and is resolved only in the caller's tenant. The request body must be {}. The business must first meet the deterministic opportunity-score threshold of 70; otherwise the API returns 409 / deterministic_threshold_not_met. An unavailable approved AI/provider configuration returns 409 / ai_provider_not_configured with no assessment output.

This route is review-only. It creates no outreach draft, pipeline change, message, browser action, or network send. Every response records network_send: false and automatic_outreach: false.

Exact assessment response

The assessment JSON has this exact shape:

{
  "opportunity_score": 0,
  "confidence_score": 0,
  "recommendation": "contact|review|low_priority|do_not_contact|insufficient_evidence",
  "priority": "high|medium|low",
  "reasons": [],
  "missing_evidence": [],
  "website_assessment": {
    "status": "healthy|outdated|broken|missing|parked|unknown",
    "broken": false,
    "outdated": false,
    "mobile_issue": false,
    "https_issue": false,
    "performance_issue": false
  },
  "domain_assessment": {
    "status": "registered|missing|likely_available|unknown"
  },
  "contactability": {
    "public_business_contact_found": false,
    "contact_type": "none|general_business|named_business|free_mail|unknown"
  },
  "recommended_services": [],
  "human_review_required": true,
  "evidence_references": []
}

• Opportunity and confidence scores are independent integers from 0–100.
• The endpoint is an internal decision surface: a contact recommendation is never permission to send outreach.
• Unknown/missing values normalize conservatively. Weak evidence (fewer than two stored evidence references), confidence below 70, or insufficient_evidence forces human review.
• Evidence references must be unique stored evidence IDs belonging to that exact business and tenant. Unknown IDs reject the provider output rather than being silently dropped. The run separately stores the schema version and evidence hashes in ai_runs.
• Active suppression always wins: recommendation becomes do_not_contact, public contactability becomes false/none, and human review remains required.
• Provider credentials remain write-only and server-side under the existing approved configuration path. The currently implemented deterministic assessment path makes no network request; any remote provider integration must use the same strict normalizer and evidence bundle.