API Reference

Base URL

https://yourdomain.com/api/

Authentication

All API requests require an API key sent in the X-API-KEY header. You can find your API key in the CleverROI dashboard under Profile.

Endpoints

POST /webhook.php

Accepts lead data, scores it, and stores it. Returns the scoring result.

Request body (JSON):

{
  "name": "Akash Singh",
  "email": "akash.digitalteam@gmail.com",
  "phone": "+918864946549",
  "budget": "10 Lakh",
  "message": "Hi, I saw your solution online. We might explore this for our clients. Please share full details and pricing.",
  "source": "facebook",
  "custom_fields": {
    "Your role": "Consultant",
    "When do you want to start?": "Not decided",
    "Are you decision maker?": "Yes",
    "Company size": "5-10",
    "Primary goal": "Exploring options"
  }
}

Response:

{
  "success": true,
  "version": "2.0.0",
  "lead_id": "lead_123abc",
  "data": {
    "score": 90,
    "grade": "Hot",
    "priority_action": "Immediate call (within 1 hour)",
    "closing_probability": "High (70-90%)",
    "reasons": [
      "Free email domain",
      "Valid phone length",
      "Valid international phone number",
      "Enterprise-level budget",
      "Detailed inquiry",
      "Source weight applied",
      "Structured signal: Numeric qualification detected",
      "AI intent: Moderate intent (confidence: medium)",
      "Risk control: Reliability-adjusted upside applied (1)",
      "Risk control: High-score dampening applied"
    ],
    "ai": {
      "score": 10,
      "max_score": 20,
      "display": "10/20",
      "impact": "Medium",
      "confidence": "medium",
      "influence_applied": 7
    },
    "contact_grade": "B"
  }
}

POST /score.php

Legacy endpoint. Same as webhook.php but may store leads differently. Use webhook.php for new integrations.

POST /explain.php

Generates a human‑readable explanation for a lead. Used internally by the dashboard.

Request body (JSON):

{
  "lead": { ... },      // lead data (same format as webhook)
  "score_data": { ... }, // optional, if already scored
  "api_key": "string"    // your API key (can also be in header)
}

Response: See the explain feature in the dashboard.

Error Handling

If an error occurs, the API returns a non‑200 HTTP status and a JSON body with an error field.

{
  "success": false,
  "error": "Description of the error"
}

Common errors: missing API key, invalid API key, plan limit reached, invalid input.