LeadContact API Integration Guide: Build Custom Workflows

LeadContact Team

LeadContact API Integration Guide: Build Custom Workflows

While the LeadContact web app and Chrome extension handle most use cases, enterprise teams often need custom workflows—automating data enrichment at scale, building integrated sales tools, or creating specialized lead generation systems. This comprehensive guide shows you how to integrate LeadContact's API into your applications.

Getting Started with LeadContact API

Authentication and Access

API Key Setup:

  1. Log into your LeadContact account at app.leadcontact.ai
  2. Navigate to Settings → API Access
  3. Generate new API key (copy securely—won't be shown again)
  4. Store API key in environment variables (never hardcode in repositories)
# Environment variable setup
LEADCONTACT_API_KEY=your_api_key_here

# Or in .env file
LEADCONTACT_API_KEY=lc_live_xxxxxxxxxxxxxx

API Base URL and Headers

API Endpoint Structure

Base URL: https://api.leadcontact.ai/v1

Required Headers:

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "User-Agent": "YourApp/1.0" // Helps LeadContact identify usage patterns
}

Rate Limits:

  • Free Plan: 25 requests/day
  • Starter Plan ($49/mo): 500 requests/day
  • Professional Plan ($99/mo): 2,000 requests/day
  • Enterprise: Custom limits (contact sales)

Core API Endpoints

Endpoint 1: Search Contacts

POST /contacts/search

Find contacts by company, name, or domain.

Request Parameters:

// Search for decision-makers at specific company
POST https://api.leadcontact.ai/v1/contacts/search

{
  "company": "Acme Corp",
  "decision_maker_only": true,
  "include_phone": true,
  "departments": ["Executive", "Engineering", "Sales"],
  "titles": ["CEO", "CTO", "VP Sales"],
  "limit": 10
}

// Response
{
  "success": true,
  "data": {
    "contacts": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@acmecorp.com",
        "email_confidence": 0.98,
        "phone": "+1-555-123-4567",
        "phone_confidence": 0.95,
        "title": "CEO",
        "company": "Acme Corp",
        "department": "Executive"
      }
    ],
    "total": 10,
    "credits_remaining": 490
  }
}

Key response fields:

  • email_confidence: 0.0 to 1.0 (0.98 = 98% confidence)
  • phone_confidence: Confidence score for phone number accuracy
  • credits_remaining: API credits left in current billing cycle

Endpoint 2: Verify Email

POST /contacts/verify

Real-time email verification via SMTP handshake.

// Verify single email
POST https://api.leadcontact.ai/v1/contacts/verify

{
  "email": "john.doe@company.com",
  "smtp_check": true,
  "format_check": true
}

// Response
{
  "success": true,
  "data": {
    "email": "john.doe@company.com",
    "is_valid": true,
    "is_deliverable": true,
    "confidence_score": 0.96,
    "smtp_response": "250 OK - Mail Accepted",
    "verification_timestamp": "2026-03-31T14:30:00Z"
  }
}

Response codes:

  • is_valid: Email format correct (syntax check)
  • is_deliverable: SMTP handshake successful (mailbox exists)
  • confidence_score: 0.90+ = verified, 0.70-0.89 = probable, <0.70 = risky

Endpoint 3: Find Phone Numbers

POST /contacts/phones

Find verified phone numbers for contacts (with or without emails).

// Find phone by email/name/company
POST https://api.leadcontact.ai/v1/contacts/phones

{
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "company": "Acme Corp",
  "include_direct_dial": true,
  "skip_mobile": false
}

// Response
{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "number": "+1-555-987-6543",
        "type": "direct_dial",
        "confidence": 0.94,
        "country_code": "US"
      }
    ]
  }
}

Integration Use Cases

Use Case 1: Automated Lead Enrichment

Scenario: Your inbound leads need contact data enrichment.

// Python example: Bulk enrichment workflow
import requests
import os

def enrich_leads(leads_list):
    """
    Enrich inbound leads with LeadContact API
    """
    api_key = os.getenv('LEADCONTACT_API_KEY')
    enriched_leads = []

    for lead in leads_list:
        # Search for contact by company domain
        response = requests.post(
            'https://api.leadcontact.ai/v1/contacts/search',
            headers={
                'Authorization': f'Bearer {api_key}',
                'Content-Type': 'application/json'
            },
            json={
                'company': lead['company'],
                'decision_maker_only': True,
                'include_phone': True,
                'departments': ['Executive']
            },
            timeout=10
        )

        if response.status_code == 200:
            data = response.json()
            if data.get('success'):
                contacts = data['data']['contacts']
                if contacts:
                    # Add best contact to lead
                    best_contact = contacts[0]  # Highest confidence
                    lead.update({
                        'email': best_contact.get('email'),
                        'phone': best_contact.get('phone'),
                        'title': best_contact.get('title'),
                        'email_confidence': best_contact.get('email_confidence')
                    })

        enriched_leads.append(lead)

    return enriched_leads

# Usage
inbound_leads = [
    {'company': 'TechCorp', 'name': 'John Doe', 'email': 'john@techcorp.com'},
    {'company': 'InnovateInc', 'name': 'Jane Smith', 'email': 'jane@innovateinc.com'}
]

enriched = enrich_leads(inbound_leads)
print(f"Enriched {len(enriched)} leads")

Use Case 2: CRM Integration

Scenario: Auto-add contacts to HubSpot when found in LeadContact.

// Node.js example: HubSpot integration
const hubspot = require('@hubspot/api-client');
const axios = require('axios');

const API_KEY = process.env.LEADCONTACT_API_KEY;
const HUBSPOT_API_KEY = process.env.HUBSPOT_API_KEY;

async function addContactToHubSpot(contact) {
  // Create contact in HubSpot
  const hubspotClient = new hubspot.Client({ apiKey: HUBSPOT_API_KEY });

  const contactObj = {
    properties: [
      { property: 'email', value: contact.email },
      { property: 'firstname', value: contact.first_name },
      { property: 'lastname', value: contact.last_name },
      { property: 'phone', value: contact.phone },
      { property: 'jobtitle', value: contact.title },
      { property: 'company', value: contact.company },
      { property: 'leadsource', value: 'LeadContact API' }
    ]
  };

  try {
    await hubspotClient.contacts.create(contactObj);
    console.log(`Added ${contact.email} to HubSpot`);
  } catch (error) {
    console.error('HubSpot error:', error);
  }
}

async function syncLeadContacts() {
  // Search for contacts from target companies
  const companies = ['Acme Corp', 'Globex Inc', 'TechStart'];

  for (const company of companies) {
    const response = await axios.post(
      'https://api.leadcontact.ai/v1/contacts/search',
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        data: {
          company: company,
          decision_maker_only: true,
          include_phone: true,
          limit: 5
        }
      }
    );

    if (response.data.success) {
      const contacts = response.data.data.contacts;

      // Add each contact to HubSpot
      for (const contact of contacts) {
        await addContactToHubSpot(contact);
      }
    }
  }
}

syncLeadContacts();

Use Case 3: Real-Time Verification

Scenario: Verify contact data before outreach to ensure deliverability.

// Go example: Pre-outreach verification
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func verifyEmailBeforeOutreach(email string) (bool, error) {
    api_key := os.Getenv("LEADCONTACT_API_KEY")

    payload := map[string]interface{}{
        "email": email,
        "smtp_check": true,
        "format_check": true,
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST",
        "https://api.leadcontact.ai/v1/contacts/verify",
        bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer " + api_key)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{Timeout: 10 * time.Second}
    resp, err := client.Do(req)

    if err != nil {
        return false, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    if result["success"].(bool) {
        data := result["data"].(map[string]interface{})
        is_valid := data["is_deliverable"].(bool)
        confidence := data["confidence_score"].(float64)

        // Only outreach if high confidence
        if is_valid && confidence >= 0.90 {
            return true, nil  // Email verified, safe to outreach
        }
        return false, nil  // Low confidence, skip outreach
    }

    return false, nil
}

Error Handling and Best Practices

  • Implement Retry Logic: Transient network failures (retry with exponential backoff: 1s, 2s, 4s)
  • Cache Responses: LeadContact data doesn't change daily—cache for 24-48 hours to reduce API calls
  • Monitor Rate Limits: Check credits_remaining in responses, implement throttling before hitting limits
  • Handle Errors Gracefully: Don't crash on 500 errors—log and retry later
  • Secure API Keys: Never commit to repositories, use environment variables or secret management services
  • Set Timeouts: 10-30 second timeouts (don't hang indefinitely on API failures)
  • Validate Inputs: Check company names, emails for valid format before API calls (save credits)

Testing Your Integration

Development workflow:

  1. Use test API key (free tier, 25 requests/day for development)
  2. Test with known companies first (validate response structure)
  3. Implement error handling before production deployment
  4. Load test with <5% of planned volume (ensure integration handles scale)
  5. Monitor API credit consumption during testing (don't exhaust production quota)

Production checklist:

  • Switch to production API key
  • Enable logging and monitoring
  • Set up alerts for high error rates or credit exhaustion
  • Document API integration for team (authentication, endpoints, data mapping)

Your API Integration Action Plan

  1. Get API Access: Generate API key from LeadContact settings
  2. Read Documentation: Review all endpoints, parameters, and response structures
  3. Build Integration: Implement authentication, error handling, and business logic
  4. Test Thoroughly: Use test key with known companies to validate workflows
  5. Implement Caching: Cache responses 24-48 hours to optimize performance and reduce credits
  6. Deploy to Production: Switch to production API key, enable monitoring
  7. Monitor Usage: Track API credit consumption, error rates, and response times

Ready to Integrate LeadContact?

Start building custom workflows that leverage LeadContact's 98% accurate contact data directly in your applications.

Get your API key from app.leadcontact.ai and begin integrating verified emails, phone numbers, and decision-maker data into your sales stack today.