Leads Overview

In Caller AI, a Lead (or Contact) is more than just a phone number. It is a structured profile that contains all the information the AI needs to have a personalized, relevant conversation.

The Lead Object Structure

Every lead in the system has a standard set of fields, but can also store unlimited custom variables. This data is available to the AI during the call.

JSON Representation of a Lead

{
  "id": "lead_xyz789",
  "phone_number": "+12125550100",
  "first_name": "Sarah",
  "last_name": "Connor",
  "email": "sarah@example.com",
  "custom_variables": {
    "account_status": "premium",
    "last_purchase_date": "2024-09-01",
    "interest": "cybersecurity"
  }
}

How Variables Work in Prompts

The power of storing this data is that you can dynamically inject it into your System Prompt. This allows a single prompt to serve thousands of unique leads.

System Prompt "Hi {{first_name}}, I see you bought a product on {{last_purchase_date}}. Since you are a {{account_status}} member, I have a special offer for you."

Lead Sources

Leads enter Caller AI through three main channels:

Manual Import (CSV): Uploading large lists for outbound campaigns.
API / Webhooks: Real-time creation (e.g., when someone fills out a form on your website).
Inbound Calls: When a new number calls your assistant, a Lead profile is automatically created for that number (initially containing just the phone number and location).

Lists vs. Global Contacts

Caller AI organizes leads into two views:

Global Contacts: The master database of everyone who has ever interacted with your assistants.
Lists (Segments): Specific groups of leads created for a Campaign (e.g., "November Outreach List"). A single lead can belong to multiple lists.

Data Privacy

Caller AI is SOC2 compliant. Lead data is encrypted at rest and in transit. You retain full ownership of your lead data and can export or delete it permanently at any time via the API or Dashboard.