Lead Ingestion API

{
  "success": true,
  "lead_id": "lead_abc123xyz",
  "message": "Lead accepted",
  "timestamp": "2024-12-25T10:30:00Z"
}

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "phone",
      "message": "Phone number must be in E.164 format"
    }
  ]
}

{
  "success": false,
  "error": "Duplicate lead detected",
  "duplicate_of": "lead_existing123",
  "similarity_score": 95,
  "matched_fields": ["email"]
}

{
  "success": false,
  "error": "Lead rejected",
  "reason": "Disposable email address not allowed",
  "rule_id": "rule_reject_disposable"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "retry_after": 60,
  "limit": 500,
  "window": "1 minute"
}

curl -X POST https://api.ledly.io/api/leads/inbound/batch \
  -H "Authorization: Bearer vk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Smith",
        "program_interest": "MBA"
      },
      {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe",
        "program_interest": "Nursing"
      },
      {
        "email": "[email protected]",
        "first_name": "Bob",
        "last_name": "Johnson",
        "program_interest": "Computer Science"
      }
    ]
  }'

{
  "success": true,
  "total": 3,
  "accepted": 2,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "success": true,
      "lead_id": "lead_abc123",
      "email": "[email protected]"
    },
    {
      "index": 1,
      "success": true,
      "lead_id": "lead_def456",
      "email": "[email protected]"
    },
    {
      "index": 2,
      "success": false,
      "email": "[email protected]",
      "error": "Duplicate lead detected",
      "duplicate_of": "lead_existing789"
    }
  ],
  "timestamp": "2024-12-25T10:30:00Z"
}

[email protected]
[email protected]
[email protected]

not-an-email
@example.com
user@
[email protected]

+1-555-123-4567
(555) 123-4567
555.123.4567
5551234567

+44 20 7123 4567  (UK)
+49 30 12345678   (Germany)
+61 2 1234 5678   (Australia)
+86 10 1234 5678  (China)

{
  "email": "[email protected]",
  "first_name": "John",
  "custom_fields": {
    "preferred_start": "Fall 2025",
    "education_level": "Bachelor's Degree",
    "years_experience": 5,
    "interested_in_scholarship": true,
    "referrer_name": "Dr. Smith",
    "notes": "Interested in evening classes"
  }
}

{
  "email": "[email protected]",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "spring-enrollment-2025",
  "utm_term": "online mba programs",
  "utm_content": "ad-variant-a"
}

async function submitLeadWithRetry(leadData, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.ledly.io/api/leads/inbound', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.LEDLY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(leadData),
      });
 
      // Success
      if (response.status === 201) {
        return await response.json();
      }
 
      // Rate limited - use Retry-After header
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
 
      // Server error - retry with exponential backoff
      if (response.status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
 
      // Client error - don't retry
      if (response.status >= 400) {
        const error = await response.json();
        throw new Error(`Lead submission failed: ${error.error}`);
      }
 
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
 
  throw new Error('Max retries exceeded');
}
 
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1703505660

{
  "success": false,
  "error": "Rate limit exceeded",
  "retry_after": 45,
  "limit": 500,
  "window": "1 minute"
}

Retry-After: 45
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703505660

Endpoint: https://sandbox.api.ledly.io/api/leads/inbound
API Key: vk_test_... (different from production)

X-Request-ID: req_abc123xyz

GET /api/leads/{lead_id}/status

{
  "id": "lead_abc123",
  "status": "accepted",
  "submitted_at": "2024-12-25T10:30:00Z",
  "processed_at": "2024-12-25T10:30:01Z",
  "validation_status": "passed",
  "enrichment_status": "completed",
  "crm_sync_status": "synced",
  "crm_id": "00Q1234567890ABC"
}

function validateLead(lead) {
  const errors = [];
 
  // Email validation
  if (!lead.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(lead.email)) {
    errors.push('Invalid email format');
  }
 
  // Phone validation (if provided)
  if (lead.phone && !/^\+?[1-9]\d{1,14}$/.test(lead.phone.replace(/[\s()-]/g, ''))) {
    errors.push('Invalid phone number');
  }
 
  return errors;
}

{
  email: '[email protected]',
  source: 'landing-page-mba',
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'spring-2025'
}

// Good - Bulk submission
await bulkIngest([lead1, lead2, lead3]);
 
// Bad - Individual submissions
await ingestLead(lead1);
await ingestLead(lead2);
await ingestLead(lead3);

if (response.status >= 400 && response.status < 500) {
  // Client error - log and don't retry
  console.error('Lead submission failed:', await response.json());
  return;
}
 
if (response.status >= 500) {
  // Server error - retry with backoff
  await retryWithBackoff();
}

const stats = {
  submitted: 0,
  accepted: 0,
  rejected: 0,
  duplicates: 0
};
 
// Alert if acceptance rate drops below 90%
if (stats.accepted / stats.submitted < 0.9) {
  alertDevTeam('Low lead acceptance rate');
}

const response = await submitLead(leadData);
const requestId = response.headers.get('X-Request-ID');
 
// Store for debugging
await logSubmission({
  leadEmail: leadData.email,
  requestId,
  timestamp: new Date(),
  success: response.status === 201
});

class LedlyClient {
  constructor(apiKey, environment = 'production') {
    this.apiKey = apiKey;
    this.baseUrl = environment === 'production'
      ? 'https://api.ledly.io/api/v1'
      : 'https://sandbox.api.ledly.io/api/v1';
  }
 
  async submitLead(leadData) {
    const response = await fetch(`${this.baseUrl}/leads/ingest`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(leadData),
    });
 
    const requestId = response.headers.get('X-Request-ID');
 
    if (!response.ok) {
      const error = await response.json();
      throw new LeadSubmissionError(error, requestId);
    }
 
    const result = await response.json();
    return { ...result, requestId };
  }
 
  async bulkSubmit(leads) {
    const response = await fetch(`${this.baseUrl}/leads/bulk-ingest`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ leads }),
    });
 
    return await response.json();
  }
}
 
// Usage
const client = new LedlyClient(process.env.LEDLY_API_KEY);
 
try {
  const result = await client.submitLead({
    email: '[email protected]',
    first_name: 'John',
    last_name: 'Doe',
    program_interest: 'MBA',
    utm_source: 'google'
  });
 
  console.log('Lead submitted:', result.lead_id);
} catch (error) {
  console.error('Submission failed:', error.message);
}