📡 LeadsPredict API

🚀 Getting Started

The LeadsPredict API allows you to analyze leads, retrieve predictions, and integrate our AI engine directly into your sales pipeline. All requests use HTTPS and return JSON.

Quick Example

curl https://api.leadspredict.com/v1/leads/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "company": "TechCorp"
      }
    ]
  }'

🔐 Authentication

All API requests require an API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

1. Sign up for a LeadsPredict account at leadspredict.com
2. Navigate to Dashboard → API Settings
3. Generate a new API key
4. Store it securely in your environment variables

⏱️ Rate Limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9950
X-RateLimit-Reset: 1699459200

📡 POST /leads/analyze

Request Body

{
  "leads": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "TechCorp",
      "industry": "Technology",
      "revenue": 5000000,
      "employees": 50,
      "engagement_score": 75,
      "last_interaction": "2025-11-01"
    }
  ],
  "options": {
    "include_predictions": true,
    "include_recommendations": true
  }
}

Response

{
  "status": "success",
  "data": {
    "leads": [
      {
        "id": "lead_abc123",
        "score": 98,
        "category": "hot",
        "conversion_probability": 0.87,
        "predicted_revenue": 125000,
        "churn_risk": "low",
        "recommendations": [
          "Contact within 24 hours",
          "Personalize outreach with industry insights"
        ],
        "next_actions": [
          {
            "action": "schedule_demo",
            "priority": "high",
            "deadline": "2025-11-10"
          }
        ]
      }
    ],
    "summary": {
      "total_leads": 1,
      "hot_leads": 1,
      "avg_score": 98,
      "total_predicted_revenue": 125000
    }
  }
}

📊 GET /leads/:id

Request

curl https://api.leadspredict.com/v1/leads/lead_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "success",
  "data": {
    "id": "lead_abc123",
    "score": 98,
    "created_at": "2025-11-08T10:00:00Z",
    "updated_at": "2025-11-08T15:30:00Z",
    "history": [
      {
        "timestamp": "2025-11-08T10:00:00Z",
        "event": "lead_created",
        "score": 85
      },
      {
        "timestamp": "2025-11-08T15:30:00Z",
        "event": "engagement_increased",
        "score": 98
      }
    ]
  }
}

🔄 POST /leads/batch

Request Body

{
  "leads": [...], // Array of up to 1000 leads
  "async": true,  // Process asynchronously
  "webhook_url": "https://your-app.com/webhook"
}

🔔 Webhooks

Subscribe to real-time events when lead scores change, predictions are updated, or actions are recommended.

Available Events

Webhook Payload

{
  "event": "lead.hot",
  "timestamp": "2025-11-08T16:00:00Z",
  "data": {
    "lead_id": "lead_abc123",
    "score": 98,
    "previous_score": 85,
    "recommendations": [...]
  }
}

⚠️ Error Handling

Error Response Format

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: email",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

📦 Official SDKs

npm install @leadspredict/node

const LeadsPredict = require('@leadspredict/node');
const client = new LeadsPredict('YOUR_API_KEY');

const result = await client.leads.analyze({
  leads: [...]
});

pip install leadspredict

from leadspredict import Client

client = Client('YOUR_API_KEY')
result = client.leads.analyze(
    leads=[...]
)

📞 Need Help?