50 lines
2.6 KiB
Markdown
50 lines
2.6 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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.
|