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": "string (optional)",
  "email": "string (optional, but at least one of email/phone required)",
  "phone": "string (optional)",
  "message": "string (optional)",
  "budget": "number (optional)",
  "source": "string (optional)"
}

Response:

{
  "success": true,
  "version": "2.0.0",
  "lead_id": "string",
  "data": {
    "score": "number",
    "grade": "string",
    "priority_action": "string",
    "closing_probability": "string",
    "reasons": ["string", ...],
    "ai": {
      "score": "number",
      "max_score": "number",
      "display": "string",
      "impact": "string",
      "confidence": "string",
      "influence_applied": "number"
    },
    "contact_grade": "string"
  }
}

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.