LeadContact API Integration Guide: Build Custom Workflows
Getting Started with LeadContact API
Authentication and Access
API Key Setup:
- Log into your LeadContact account at app.leadcontact.ai
- Navigate to Settings → API Access
- Generate new API key (copy securely—won't be shown again)
- 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_remainingin 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:
- Use test API key (free tier, 25 requests/day for development)
- Test with known companies first (validate response structure)
- Implement error handling before production deployment
- Load test with <5% of planned volume (ensure integration handles scale)
- 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
- Get API Access: Generate API key from LeadContact settings
- Read Documentation: Review all endpoints, parameters, and response structures
- Build Integration: Implement authentication, error handling, and business logic
- Test Thoroughly: Use test key with known companies to validate workflows
- Implement Caching: Cache responses 24-48 hours to optimize performance and reduce credits
- Deploy to Production: Switch to production API key, enable monitoring
- 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.
