Watched Leads API

Manage user watch lists for tracking specific leads and monitoring their engagement over time.

POST /leads/{leadID}/watch

Add a lead to the authenticated user's watch list.

Request

Parameter	Type	Required	Description
leadID	string	Yes	Lead identifier (path parameter)
prediction	string	No	Optional prediction about lead outcome
prediction_notes	string	No	Notes explaining the prediction

Request Body

{
  "prediction": "will_convert",
  "prediction_notes": "Strong engagement on pricing page + demo request"
}

Response

201 Created

{
  "watch_id": "watch_abc123",
  "lead_id": "ld_123",
  "message": "Lead added to watch list"
}

Example

curl -X POST "https://api.leadvibe.com/leads/ld_123/watch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prediction": "will_convert",
    "prediction_notes": "High buying intent based on recent activity"
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	Lead ID is required
401	Unauthorized	Check authentication token
404	Not Found	Lead does not exist or not accessible

---

DELETE /leads/{leadID}/watch

Remove a lead from the authenticated user's watch list.

Request

Parameter	Type	Required	Description
leadID	string	Yes	Lead identifier (path parameter)

Response

204 No Content

Successfully removed from watch list.

Example

curl -X DELETE "https://api.leadvibe.com/leads/ld_123/watch" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
404	Not Found	Lead not in watch list or doesn't exist

---

GET /watched-leads

Retrieve the authenticated user's complete watch list with current scores and score changes.

Request

No parameters required. Returns all leads watched by the authenticated user.

Response

200 OK

{
  "watched_leads": [
    {
      "watch_id": "watch_abc123",
      "lead_id": "ld_123",
      "prediction": "will_convert",
      "prediction_notes": "Strong engagement signals",
      "watched_at": "2025-01-15T10:00:00Z",
      "outcome": "pending",
      "outcome_at": null,
      "current_score": 75,
      "score_at_watch": 60,
      "score_delta": 15
    },
    {
      "watch_id": "watch_def456",
      "lead_id": "ld_456",
      "prediction": "high_value",
      "prediction_notes": "Enterprise account, multiple touchpoints",
      "watched_at": "2025-01-14T15:30:00Z",
      "outcome": "pending",
      "outcome_at": null,
      "current_score": 92,
      "score_at_watch": 85,
      "score_delta": 7
    }
  ],
  "count": 2
}

Response Fields

Field	Type	Description
watch_id	string	Unique watch record identifier
lead_id	string	Lead identifier
prediction	string	Optional prediction about outcome
prediction_notes	string	Optional notes explaining prediction
watched_at	timestamp	When lead was added to watch list
outcome	string	Outcome status: "pending", "won", "lost"
outcome_at	timestamp	When outcome was recorded (null if pending)
current_score	integer	Lead's current score
score_at_watch	integer	Score when lead was added to watch list
score_delta	integer	Change in score since watching (current - at_watch)

Example

curl -X GET "https://api.leadvibe.com/watched-leads" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

GET /watched-leads/stats

Get prediction accuracy statistics for the authenticated user.

Request

No parameters required.

Response

200 OK

{
  "total_watched": 25,
  "total_predictions": 20,
  "correct_predictions": 15,
  "pending_outcomes": 8,
  "accuracy_percent": 75.0
}

Response Fields

Field	Type	Description
total_watched	integer	Total number of leads ever watched
total_predictions	integer	Number of watches with predictions
correct_predictions	integer	Predictions that came true (outcome = "won")
pending_outcomes	integer	Leads still pending outcome
accuracy_percent	number	Percentage of correct predictions (correct / total * 100)

Example

curl -X GET "https://api.leadvibe.com/watched-leads/stats" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

Use Cases

Track High-Value Prospects

Watch leads that match your ideal customer profile to monitor engagement trends.

# Watch a lead
curl -X POST "https://api.leadvibe.com/leads/ld_123/watch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prediction": "will_convert",
    "prediction_notes": "Perfect ICP match + high engagement"
  }'

# Check score changes later
curl -X GET "https://api.leadvibe.com/watched-leads" \
  -H "Authorization: Bearer <token>"

Monitor Prediction Accuracy

Track how well your lead qualification intuition performs over time.

# Get accuracy stats
curl -X GET "https://api.leadvibe.com/watched-leads/stats" \
  -H "Authorization: Bearer <token>"

Clean Up Watch List

Remove leads that have converted or gone cold.

# Remove lead from watch list
curl -X DELETE "https://api.leadvibe.com/leads/ld_123/watch" \
  -H "Authorization: Bearer <token>"

---

Notes

• Watch lists are personal and private to each user
• Score snapshots are captured hourly for all leads
• Score delta is calculated using the nearest snapshot to watch time
• Predictions are optional but help track qualification accuracy
• Outcome tracking (won/lost) is currently manual (future enhancement)
• Watch data is OU-scoped like all lead data