Lead Lists

Uploading Lists

Lead lists are collections of contacts that you attach to campaigns. You can upload via the dashboard (CSV/XLSX) or the API (JSON).

Dashboard Upload

Go to Lists → New List
Name your list
Upload a CSV or XLSX file
Map columns to fields (email, first_name, last_name, company)
Any unmapped columns are stored as custom fields in extra_data

Required column

The only required column is email. All other fields are optional but improve personalization.

API Upload

bash

curl -X POST http://YOUR_SERVER/v1/outreach/lists \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_SESSION" \
  -d '{
    "name": "Enterprise Leads Q2",
    "leads": [
      {
        "email": "john@acme.com",
        "first_name": "John",
        "last_name": "Smith",
        "company": "Acme Corp",
        "extra_data": {"title": "VP Sales", "linkedin": "linkedin.com/in/john"}
      },
      {
        "email": "jane@startup.io",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Startup Inc"
      }
    ]
  }'

CSV Format

leads.csv

email,first_name,last_name,company,title
john@acme.com,John,Smith,Acme Corp,VP Sales
jane@startup.io,Jane,Doe,Startup Inc,CEO
bob@enterprise.com,Bob,Johnson,Enterprise Ltd,CTO

Custom Fields

Any column not matching the standard fields (email, first_name, last_name, company) is stored as JSON in the lead's extra_data field. You can reference these in personalization:

text

Hi {{FIRST_NAME}}, I noticed you're the {{title}} at {{COMPANY}}...

List Properties

Property	Description
Status	active (default)
Validation Status	unvalidated, processing, completed
Initial Count	Number of leads when validation started
Processed Count	Leads validated so far
Invalid Deleted	Leads removed as invalid
Catchall Deleted	Leads removed as catch-all (if strategy is "delete")

Downloading Lists

Export a validated list as CSV (includes validation results and all custom fields):

bash

curl http://YOUR_SERVER/v1/outreach/lists/LIST_ID/download \
  -H "Cookie: auth_token=YOUR_SESSION" \
  -o cleaned_list.csv