Lead Recovery

Analyze a single lead and receive a Recovery Score with a recommended next action.

Endpoint

POST /api/v1/leads/recovery

This endpoint also accepts a { leads: [...] } body as a convenience, but for large jobs prefer the dedicated batch endpoint.

Request fields

Field	Type	Description
status*	enum	Pipeline stage: new, contacted, quote_requested, estimate_sent, proposal_sent, negotiating, no_response, closed_won, closed_lost, opted_out.
lead_age_days*	integer	Days since the lead was created. Must be >= 0.
industry	enum	hvac, plumbing, electrical, roofing, automotive, b2b_sales, generic. Defaults to generic.
lead_id	string	Your identifier, echoed back on the response.
last_contact_days	integer	Days since last contact. Recent contact lifts the score.
contact_attempts	integer	Prior follow-up attempts. Few attempts help; excessive attempts hurt.
estimate_value	number	Estimate or deal value in your currency. Higher value increases recovery priority.
source	string	Lead source, e.g. referral, website, google_ads, cold_email.
explicit_rejection	boolean	Whether the lead explicitly declined. Caps the score.
opted_out	boolean	Whether the lead opted out of contact. Recommends archive.
previous_customer	boolean	Whether this is an existing customer.
prior_engagement	boolean	Whether the lead engaged previously.
repeat_service	boolean	Repeat-service opportunity (weighted by industry).
invalid_contact	boolean	Whether contact info is invalid. Caps the score.
duplicate	boolean	Whether the lead is a suspected duplicate.
closed_lost_reason	string	Reason for a closed_lost status.
first_name	string	Used only to personalize the suggested message.

Example request

Request

POST /api/v1/leads/recovery
Authorization: Bearer stx_live_...
Content-Type: application/json

{
  "lead_id": "lead_123",
  "industry": "hvac",
  "status": "estimate_sent",
  "lead_age_days": 47,
  "last_contact_days": 31,
  "contact_attempts": 2,
  "estimate_value": 8500,
  "source": "website",
  "explicit_rejection": false
}

Example response

200 OK

{
  "request_id": "req_xxx",
  "lead_id": "lead_123",
  "recovery_score": 74,
  "priority": "high",
  "recommended_action": "follow_up",
  "recommended_channel": "sms",
  "recommended_timing": "today",
  "reason": "High-value estimate with no explicit rejection and limited recent follow-up.",
  "suggested_message": "Hi {{first_name}}, following up on the estimate we sent...",
  "confidence": 0.90,
  "factors": [
    { "factor": "estimate_value", "impact": "positive", "score_effect": 11 },
    { "factor": "status", "impact": "positive", "score_effect": 20 }
  ],
  "scoring_version": "1.0.0"
}