Lead lists workflow

Lead Lists Workflow Guide

This guide demonstrates how to use the Lead Lists API endpoints together to build a complete workflow for managing leads.

Overview

The Lead Lists API provides a complete set of endpoints for:

Searching for prospects or companies using filters
Creating lead lists (people or company lists)
Adding found leads to your lists
Retrieving leads from your lists
Deleting leads from your lists
Importing leads into campaigns

Complete Workflow Example

Step 1: Create a Lead List

First, create a new lead list. Choose the type based on whether you want to manage people or companies.

import requests

API_KEY = "<your-api-key>"
BASE_URL = "https://api.seleqt.ai/api/v1"

# Create a people list
response = requests.post(
    f"{BASE_URL}/public/lead-lists/",
    headers={"X-API-Key": API_KEY},
    json={
        "name": "Tech CEOs for Q4 Campaign",
        "search_type": "PEOPLE"
    }
)

lead_list = response.json()["lead_list"]
lead_list_id = lead_list["id"]
print(f"Created lead list: {lead_list['name']} (ID: {lead_list_id})")

Step 2: Search for Prospects

Search for prospects using various filters. The search respects your organization’s search limits.

# Search for prospects with specific criteria
search_response = requests.post(
    f"{BASE_URL}/public/prospects/search/",
    headers={"X-API-Key": API_KEY},
    json={
        "search_type": "PEOPLE",
        "page": 1,
        "page_size": 100,
        "filters": {
            "job_title": "CEO",
            "location": "United States",
            "industry": "Technology",
            "company_size": "51-200"
        }
    }
)

search_data = search_response.json()
print(f"Found {search_data['total_count']} prospects")
prospects = search_data["prospects"]

Step 3: Add Prospects to Your List

Extract the prospect IDs from search results and add them to your lead list.

# Get prospect IDs
prospect_ids = [p["id"] for p in prospects[:50]]  # Add first 50

# Add to lead list
add_response = requests.post(
    f"{BASE_URL}/public/lead-lists/{lead_list_id}/add-leads/",
    headers={"X-API-Key": API_KEY},
    json={"prospect_ids": prospect_ids}
)

print(f"Added {add_response.json()['added_count']} prospects to list")

Step 4: Review and Filter Your List

Retrieve leads from your list with additional filtering or sorting.

# Get all leads from the list
list_response = requests.get(
    f"{BASE_URL}/public/lead-lists/{lead_list_id}/leads/",
    headers={"X-API-Key": API_KEY},
    params={
        "page": 1,
        "page_size": 100,
        "sort_field": "last_name",
        "sort_direction": "asc"
    }
)

list_data = list_response.json()
print(f"List contains {list_data['total_count']} total prospects")

Step 5: Clean Up Your List (Optional)

Remove prospects that don’t meet your criteria.

# Find prospects to remove (e.g., based on some criteria)
prospects_to_remove = [p["id"] for p in list_data["prospects"] if some_condition(p)]

if prospects_to_remove:
    delete_response = requests.delete(
        f"{BASE_URL}/public/lead-lists/{lead_list_id}/delete-leads/",
        headers={"X-API-Key": API_KEY},
        json={"prospect_ids": prospects_to_remove}
    )
    print(f"Removed {delete_response.json()['deleted_count']} prospects")

Step 6: Enrich Email/Phone (Optional)

Before importing to campaigns, you may want to enrich missing contact information.

# Check how many prospects need email enrichment
enrich_count_response = requests.get(
    f"{BASE_URL}/public/lead-lists/{lead_list_id}/enrichment/count/",
    headers={"X-API-Key": API_KEY},
    params={"enrichment_type": "FIND_EMAIL"}
)

enrich_count = enrich_count_response.json()
print(f"Prospects without emails: {enrich_count['unenriched_count']}")
print(f"Cost to enrich: {enrich_count['total_cost']} credits")

# Enrich emails if you have enough credits
if enrich_count['has_enough_credits'] and enrich_count['unenriched_count'] > 0:
    enrich_response = requests.post(
        f"{BASE_URL}/public/lead-lists/{lead_list_id}/enrichment/",
        headers={"X-API-Key": API_KEY},
        json={
            "enrichment_type": "FIND_EMAIL",
            "prospect_limit": enrich_count['unenriched_count']
        }
    )

    if enrich_response.json()['success']:
        print(f"Enriching emails for {enrich_count['unenriched_count']} prospects...")
        # Enrichment happens in background
        time.sleep(30)  # Wait for some results

Step 7: Import to Campaign

Once your list is ready, import it into a campaign for outreach.

# Get or create a campaign
campaign_response = requests.post(
    f"{BASE_URL}/public/campaigns/",
    headers={"X-API-Key": API_KEY},
    json={
        "name": "Q4 Tech CEO Outreach",
        "status": "DRAFT"
    }
)

campaign_id = campaign_response.json()["campaign"]["id"]

# Import leads from list to campaign
import_response = requests.post(
    f"{BASE_URL}/public/campaigns/{campaign_id}/import/",
    headers={"X-API-Key": API_KEY},
    json={
        "source": "lead_list",
        "lead_list_id": lead_list_id,
        "amount": 100  # Number of leads to import
    }
)

print(f"Imported leads into campaign")

Working with Company Lists

The workflow for company lists is similar, but uses company_ids instead of prospect_ids.

# Create a company list
company_list_response = requests.post(
    f"{BASE_URL}/public/lead-lists/",
    headers={"X-API-Key": API_KEY},
    json={
        "name": "SaaS Companies to Target",
        "search_type": "COMPANY"
    }
)

company_list_id = company_list_response.json()["lead_list"]["id"]

# Search for companies
company_search_response = requests.post(
    f"{BASE_URL}/public/prospects/search/",
    headers={"X-API-Key": API_KEY},
    json={
        "search_type": "COMPANY",
        "filters": {
            "industry": "Software",
            "company_size": "11-50",
            "location": "United States"
        }
    }
)

companies = company_search_response.json()["companies"]
company_ids = [c["id"] for c in companies]

# Add companies to list
requests.post(
    f"{BASE_URL}/public/lead-lists/{company_list_id}/add-leads/",
    headers={"X-API-Key": API_KEY},
    json={"company_ids": company_ids}
)

Advanced: Batch Processing

For large-scale operations, use pagination to process all results.

def search_all_prospects(filters, search_type="PEOPLE"):
    """Search all prospects matching filters across all pages."""
    all_prospects = []
    page = 1

    while True:
        response = requests.post(
            f"{BASE_URL}/public/prospects/search/",
            headers={"X-API-Key": API_KEY},
            json={
                "search_type": search_type,
                "page": page,
                "page_size": 100,
                "filters": filters
            }
        )

        data = response.json()
        prospects = data["prospects"]
        all_prospects.extend(prospects)

        # Check if we've reached the last page
        if len(prospects) < 100:
            break

        page += 1

    return all_prospects

# Use the function
all_ceos = search_all_prospects({
    "job_title": "CEO",
    "industry": "Technology"
})

print(f"Found {len(all_ceos)} total CEOs")

Error Handling

Always implement proper error handling in production code.

def safe_api_call(method, url, **kwargs):
    """Make API call with error handling."""
    try:
        response = method(url, **kwargs)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error: {e}")
        print(f"Response: {e.response.text}")
        return None
    except Exception as e:
        print(f"Error: {e}")
        return None

# Use safe API calls
data = safe_api_call(
    requests.post,
    f"{BASE_URL}/public/prospects/search/",
    headers={"X-API-Key": API_KEY},
    json={"search_type": "PEOPLE", "filters": {"job_title": "CEO"}}
)

if data and data.get("success"):
    prospects = data["prospects"]
    # Process prospects

Enrichment Workflow

Email and phone enrichment is a powerful feature for lead lists:

def enrich_lead_list(lead_list_id, enrichment_type="FIND_EMAIL"):
    """
    Complete enrichment workflow with error handling.
    """
    # Step 1: Check cost
    count_response = requests.get(
        f"{BASE_URL}/public/lead-lists/{lead_list_id}/enrichment/count/",
        headers={"X-API-Key": API_KEY},
        params={"enrichment_type": enrichment_type}
    )

    if not count_response.ok:
        print(f"Error: {count_response.text}")
        return False

    count_data = count_response.json()

    # Step 2: Validate we have enough credits
    if not count_data['has_enough_credits']:
        print(f"Insufficient credits: need {count_data['total_cost']}, have {count_data['available_credits']}")
        return False

    if count_data['unenriched_count'] == 0:
        print("No prospects need enrichment")
        return True

    # Step 3: Confirm with user (in production, you might skip this)
    print(f"Will enrich {count_data['unenriched_count']} prospects")
    print(f"Cost: {count_data['total_cost']} credits")

    # Step 4: Start enrichment
    enrich_response = requests.post(
        f"{BASE_URL}/public/lead-lists/{lead_list_id}/enrichment/",
        headers={"X-API-Key": API_KEY},
        json={
            "enrichment_type": enrichment_type,
            "prospect_limit": count_data['unenriched_count']
        }
    )

    if enrich_response.ok:
        result = enrich_response.json()
        print(f"✓ Enrichment started: {result['enriched_count']} prospects")
        print(f"✓ Credits deducted: {result['credits_deducted']}")
        return True
    else:
        print(f"Error: {enrich_response.text}")
        return False

# Use it
enrich_lead_list(123, "FIND_EMAIL")

Best Practices

Pagination: Always use pagination when dealing with large result sets
Error Handling: Implement retry logic for transient errors
Rate Limiting: Be mindful of API rate limits
Search Limits: Monitor your organization’s monthly search limit
Data Validation: Validate prospect/company IDs before adding to lists
List Organization: Use descriptive names for your lead lists
Regular Cleanup: Remove outdated or invalid leads periodically
Check Enrichment Costs: Always check costs before enriching
Enrich Strategically: Email enrichment is cheaper than phone (3 vs 30 credits)
Monitor Credits: Keep track of your credit balance to avoid interruptions

API Endpoints Summary

Endpoint	Method	Purpose
`/public/lead-lists/`	POST	Create a lead list
`/public/lead-lists/`	GET	List all lead lists
`/public/prospects/search/`	POST	Search for prospects/companies
`/public/lead-lists/:id/add-leads/`	POST	Add leads to a list
`/public/lead-lists/:id/leads/`	GET	Get leads from a list
`/public/lead-lists/:id/delete-leads/`	DELETE	Delete leads from a list
`/public/lead-lists/:id/enrichment/count/`	GET	Get enrichment cost estimate
`/public/lead-lists/:id/enrichment/`	POST	Enrich emails/phones
`/public/lead-lists/:id/import/`	POST	Import leads to a list
`/public/campaigns/{id}/import/`	POST	Import leads to a campaign

Getting Started

API Reference

Public API

Webhooks