API Documentation

Leads API

The Leads API allows you to create leads in your CRM from external sources like website forms, landing pages, or other applications.

Create Lead

Submit a new lead to your CRM pipeline.

Endpoint: POST /api/v1/leads
Required Scope: write:leads

Request Body

FieldTypeRequiredDescription
namestringYesLead's full name
emailstringYesLead's email address
phonestringNoLead's phone number
companystringNoLead's company name
sourcestringNoLead source (e.g., "website_form", "landing_page")
notesstringNoAdditional notes
cURLbash
curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1 (555) 123-4567",
    "company": "Acme Corp",
    "source": "website_contact_form",
    "notes": "Interested in enterprise plan"
  }'
JavaScriptjavascript
const response = await fetch('https://yourdomain.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Jane Smith',
    email: 'jane@example.com',
    phone: '+1 (555) 123-4567',
    company: 'Acme Corp',
    source: 'website_contact_form',
    notes: 'Interested in enterprise plan'
  })
});
const lead = await response.json();
Pythonpython
import requests

response = requests.post(
    'https://yourdomain.com/api/v1/leads',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Jane Smith',
        'email': 'jane@example.com',
        'phone': '+1 (555) 123-4567',
        'company': 'Acme Corp',
        'source': 'website_contact_form',
        'notes': 'Interested in enterprise plan'
    }
)
lead = response.json()

Common Use Cases

Website Contact Form

Capture leads from your website contact form:

document.getElementById('contactForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(e.target);

  await fetch('https://yourdomain.com/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: formData.get('name'),
      email: formData.get('email'),
      phone: formData.get('phone'),
      notes: formData.get('message'),
      source: 'website_contact_form'
    })
  });

  alert('Thank you! We\'ll be in touch soon.');
});

Landing Page Integration

Track leads from marketing landing pages and automatically add them to your CRM for follow-up.

Webinar Registration

Capture webinar registrations and send confirmation emails while adding leads to your pipeline.

Lead Status Flow

When a lead is created via the API, it enters your CRM with the status new. Your team can then move the lead through your pipeline:

new → contacted → qualified → proposal → won/lost

You can view and manage leads in your CRM Dashboard.

Duplicate Handling

Duplicate Detection

Leads are matched by email address. If a lead with the same email already exists, the API will return a 200 success response (not 201) and update the existing lead with new information.

Best Practices

  1. Always include source: Track where leads come from for better analytics
  2. Add context in notes: Include relevant details about the lead's interest
  3. Validate emails client-side: Reduce errors by validating before submission
  4. Handle errors gracefully: Show user-friendly messages when API calls fail
  5. Implement rate limiting: Prevent abuse by limiting form submissions

Next Steps