INTEGRATE LEADS DIRECTLY
INTO YOUR CRM

Authentication

All API requests must be authenticated using a Bearer token. Your API key is available in your buyer dashboard under Settings → API Access.

Authorization: Bearer YOUR_API_KEY

Include this header in every request. Keys are tied to your buyer account and inherit your plan's permissions and rate limits.

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited per API key. Exceeding the limit returns a 429 Too Many Requests response.

Rate limit headers are returned on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1716196800

Error Codes

All errors return a consistent JSON body with a code and human-readable message.

List Your Leads

Retrieve a paginated list of leads delivered to your account. Use query parameters to filter by vertical, score tier, location, or date range.

{
  "leads": [
    {
      "id": "lead_abc123",
      "vertical": "solar",
      "sub_vertical": "installation",
      "first_name": "Thabo",
      "suburb": "Sandton",
      "province": "Gauteng",
      "score_tier": "hot",
      "service_type": "Solar Installation 10kW+",
      "delivered_at": "2026-05-20T10:23:48Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 25
}

Get Single Lead

Retrieve the full detail of a single lead including the quality score breakdown. Only returns leads that were delivered to your account.

{
  "id": "lead_abc123",
  "vertical": "solar",
  "sub_vertical": "installation",
  "first_name": "Thabo",
  "suburb": "Sandton",
  "province": "Gauteng",
  "service_type": "Solar Installation 10kW+",
  "budget_range": "R100,000–R150,000",
  "urgency": "asap",
  "phone": "+27823456789",
  "email": "thabo.m@gmail.com",
  "score": 87,
  "score_tier": "hot",
  "score_breakdown": {
    "phone_valid": 10,
    "email_valid": 8,
    "suburb_match": 8,
    "budget_provided": 10,
    "urgency_high": 12,
    "form_complete": 10,
    "service_specific": 10,
    "real_name": 8,
    "organic_source": 6,
    "intent_score": 5
  },
  "delivered_at": "2026-05-20T10:23:48Z",
  "created_at": "2026-05-20T10:23:44Z"
}

Register a Webhook

Register a webhook URL to receive leads in real time as they are matched to your account. Leaditio will POST the webhook payload to your URL within seconds of a lead qualifying.

{
  "url": "https://your-crm.com/hooks/leaditio",
  "secret": "wh_secret_your_secret_here",
  "events": ["lead.new", "lead.updated"]
}

{
  "webhook_id": "wh_7f3a2b9c",
  "url": "https://your-crm.com/hooks/leaditio",
  "events": ["lead.new", "lead.updated"],
  "created_at": "2026-05-20T10:00:00Z"
}

Account Statistics

Retrieve high-level statistics for your buyer account including leads received, conversion rate, and your active subscription plan.

{
  "leads_received": 142,
  "leads_converted": 31,
  "conversion_rate": "21.8%",
  "leads_this_month": 38,
  "quota_this_month": 150,
  "active_plan": "pro",
  "plan_renews_at": "2026-06-01T00:00:00Z"
}

Webhook Payload Reference

When a new lead is matched to your account, Leaditio sends an HTTP POST to your registered webhook URL within seconds. The request body is JSON and includes the full lead record.

{
  "event": "lead.new",
  "timestamp": "2026-05-20T10:23:44Z",
  "lead": {
    "id": "lead_abc123",
    "vertical": "solar",
    "sub_vertical": "installation",
    "first_name": "Thabo",
    "suburb": "Sandton",
    "province": "Gauteng",
    "score": 87,
    "score_tier": "hot",
    "service_type": "Solar Installation 10kW+",
    "budget_range": "R100,000–R150,000",
    "urgency": "asap",
    "delivered_at": "2026-05-20T10:23:48Z"
  },
  "contact": {
    "phone": "+27823456789",
    "email": "thabo.m@gmail.com"
  }
}

Signature Verification

Every webhook request includes an X-Leaditio-Signature header. This is an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Always verify this to ensure the request is genuine.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Event Types

Fetching Your Leads

Example code to authenticate and retrieve leads from the Leaditio API in three popular languages.

// Fetch leads using the Leaditio REST API
const API_KEY = process.env.LEADITIO_API_KEY;
const BASE_URL = 'https://leaditio.com/api/v1';

async function getLeads({ vertical, scoreTier, page = 1, limit = 25 } = {}) {
  const params = new URLSearchParams({ page, limit });
  if (vertical) params.set('vertical', vertical);
  if (scoreTier) params.set('score_tier', scoreTier);

  const res = await fetch(`${BASE_URL}/leads?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.message);
  }

  return res.json(); // { leads, total, page, limit }
}

// Usage
getLeads({ vertical: 'solar', scoreTier: 'hot' })
  .then(data => console.log(data.leads))
  .catch(console.error);

# pip install requests
import os
import requests

API_KEY = os.environ['LEADITIO_API_KEY']
BASE_URL = 'https://leaditio.com/api/v1'

def get_leads(vertical=None, score_tier=None, page=1, limit=25):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    params = {'page': page, 'limit': limit}
    if vertical:
        params['vertical'] = vertical
    if score_tier:
        params['score_tier'] = score_tier

    response = requests.get(
        f'{BASE_URL}/leads',
        headers=headers,
        params=params
    )
    response.raise_for_status()
    return response.json()  # { leads, total, page, limit }

# Usage
data = get_leads(vertical='solar', score_tier='hot')
for lead in data['leads']:
    print(lead['id'], lead['suburb'], lead['score_tier'])

# List all hot solar leads
curl -X GET "https://leaditio.com/api/v1/leads?vertical=solar&score_tier=hot&page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Get a specific lead
curl -X GET "https://leaditio.com/api/v1/leads/lead_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Register a webhook
curl -X POST "https://leaditio.com/api/v1/leads/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-crm.com/hooks/leaditio","secret":"your_secret","events":["lead.new","lead.updated"]}'

# Get account stats
curl -X GET "https://leaditio.com/api/v1/account/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

CRM Integrations

Connect Leaditio to your existing sales stack. Native integrations and webhook-based flows are available for all major CRM platforms used in South Africa.