Leads - Feather

What Are Leads?

Leads are customer contacts in your Feather organization. They represent individuals your agents interact with through calls, texts, and workflows. Leads store contact information, conversation history, and metadata that enables personalized, context-aware interactions. Think of leads as your customer database that:

Store contact information - Names, phone numbers, emails, and custom fields
Track conversation history - All interactions across time
Enable personalization - Agents access previous conversation context
Power workflows - Workflow executions target specific leads
Maintain memories - AI remembers key information from past conversations

Lead Structure

Basic Lead Information

Leads contain core contact details:

{
  id: "lead-123",
  firstName: "Sarah",
  lastName: "Johnson",
  email: "sarah.johnson@example.com",
  phoneNumber: "+14155551234",
  customFields: {
    company: "Acme Corp",
    role: "VP of Sales",
    industry: "Technology",
    leadSource: "Website Form"
  }
}

Conversation Memories

Each lead has memories - key information extracted from conversations:

{
  leadId: "lead-123",
  memories: [
    {
      content: "Interested in Enterprise plan",
      timestamp: "2024-01-15T10:30:00Z",
      callId: "call-456"
    },
    {
      content: "Prefers Tuesday afternoons for demos",
      timestamp: "2024-01-15T10:31:00Z",
      callId: "call-456"
    },
    {
      content: "Budget approved for Q1",
      timestamp: "2024-01-18T14:20:00Z",
      callId: "call-789"
    }
  ]
}

Managing Leads

Listing All Leads

Retrieve leads in your organization:

const response = await fetch('https://prod.featherhq.com/api/v1/leads', {
  headers: {
    'X-API-Key': API_KEY
  }
});

const leads = await response.json();

leads.forEach(lead => {
  console.log(`${lead.firstName} ${lead.lastName} - ${lead.phoneNumber}`);
});

Viewing Lead Memories

Access conversation history for a lead:

const leadId = "lead-123";

const response = await fetch(`https://prod.featherhq.com/api/v1/leads/${leadId}/memories`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const memories = await response.json();

memories.forEach(memory => {
  console.log(`[${memory.timestamp}] ${memory.content}`);
});

Leads in Agent Conversations

Memory Creation

Agents automatically create memories during conversations when they learn important information:

Agent: "What industry are you in?"
Customer: "We're in healthcare technology"
→ Memory created: "Works in healthcare technology"

Agent: "When would be a good time for a demo?"
Customer: "Wednesdays work best for me"
→ Memory created: "Prefers Wednesday demos"

Memory Recall

In subsequent conversations, agents access these memories:

Agent: "Hi Sarah! Last time we spoke, you mentioned you work in healthcare
       technology. I have some updates on our HIPAA-compliant features."

Configuring Memory in Agents

Enable and configure memory in your agent prompts:

{
  prompt: {
    system: `You are a sales agent. Pay attention to customer preferences
             and important details. Store key information as memories for
             future conversations.

When you learn:
- Budget information
- Timeline preferences
- Pain points
- Decision makers
- Specific requirements

Create a memory so future agents can reference this information.`
  }
}

Leads in Workflows

Workflow Executions

Workflows target specific leads:

const execution = {
  workflowId: "workflow-123",
  customerLeadId: "lead-456",  // The lead being contacted
  variables: {
    firstName: "Sarah",
    productName: "Enterprise Plan",
    lastInteraction: "2024-01-15"
  }
};

const response = await fetch('https://prod.featherhq.com/api/v1/workflow-execution', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(execution)
});

Lead Variables in Workflows

Reference lead data in workflow steps:

{
  "steps": [
    {
      "type": "CALL",
      "order": 1,
      "agentId": "agent-123"
    },
    {
      "type": "TEXT",
      "order": 2,
      "message": "Hi {{firstName}}, following up on our call about {{productInterest}}. {{calendarLink}}"
    }
  ]
}

Leads in Dispatches

Agent Dispatch with Lead Context

When dispatching agents, provide lead information:

const dispatch = {
  leadId: "lead-789",
  firstName: "Michael",
  lastName: "Chen",
  toPhoneNumber: "+14155559876",
  mode: "audio",
  customData: {
    accountValue: "$50,000",
    lastPurchase: "2024-01-10",
    tier: "premium"
  }
};

const response = await fetch(`https://prod.featherhq.com/api/v1/agent/${agentId}/dispatch`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(dispatch)
});

Custom Fields and Metadata

Structuring Lead Data

Organize lead information with custom fields:

const leadData = {
  // Standard fields
  firstName: "Emily",
  lastName: "Rodriguez",
  email: "emily@techstartup.com",
  phoneNumber: "+14155554321",

  // Custom fields for your business
  customFields: {
    // Sales data
    leadScore: 85,
    leadSource: "LinkedIn",
    estimatedValue: "$25,000",
    expectedCloseDate: "2024-03-15",

    // Company data
    companyName: "TechStartup Inc",
    companySize: "50-100",
    industry: "SaaS",

    // Interaction data
    lastContactDate: "2024-01-20",
    numberOfTouches: 3,
    preferredContactMethod: "phone",

    // Qualification data
    budget: "approved",
    authority: "decision maker",
    need: "urgent",
    timeline: "Q1 2024"
  }
};

Using Custom Fields in Conversations

Agents can reference custom fields:

{
  prompt: {
    system: `You are a sales agent. You have access to lead information:

- Lead Score: {{leadScore}}
- Company: {{companyName}} ({{companySize}} employees)
- Industry: {{industry}}
- Expected Close: {{expectedCloseDate}}

Tailor your conversation based on this context. High-value leads (score > 80)
should receive premium attention.`
  }
}

Lead Lifecycle

Lead States

Track leads through your pipeline:

const leadStates = [
  "new",           // Newly acquired lead
  "contacted",     // First touch made
  "qualified",     // Meets qualification criteria
  "proposal",      // Proposal sent
  "negotiation",   // In negotiation
  "closed-won",    // Successfully converted
  "closed-lost",   // Did not convert
  "nurturing",     // Long-term nurture
  "dnc"            // Do not contact
];

Update lead state after interactions:

{
  customFields: {
    status: "qualified",
    lastStatusChange: "2024-01-20T15:30:00Z",
    qualificationDate: "2024-01-20",
    qualifiedBy: "agent-123"
  }
}

Conversation Context

Building Context Over Time

Leads accumulate context through multiple interactions: Interaction 1 (Jan 15):

Agent: "What challenges are you facing?"
Lead: "We need better customer support automation"
→ Memory: "Looking for customer support automation"

Interaction 2 (Jan 18):

Agent: "Last time you mentioned needing support automation. I'd like to
       show you how our platform handles that."
Lead: "Yes, specifically for after-hours support"
→ Memory: "Needs after-hours support automation"

Interaction 3 (Jan 22):

Agent: "Based on your needs for after-hours customer support automation,
       I've prepared a demo focused on our automated routing features..."

Memory-Driven Personalization

Use accumulated memories to personalize experiences:

// Agent prompt with memory integration
{
  system: `You are a sales agent. Review this lead's conversation history:

{{#each leadMemories}}
- {{this.content}} ({{this.timestamp}})
{{/each}}

Use this context to:
1. Reference past conversations naturally
2. Avoid asking questions already answered
3. Build on previous discussions
4. Show you remember details they've shared`
}

Lead Tools Integration

Updating Leads During Calls

Create tools to update lead information:

{
  name: "Update Lead Status",
  slug: "update_lead_status",
  structure: {
    url: "https://api.yourcrm.com/leads/{{leadId}}",
    method: "PATCH",
    headers: {
      "Authorization": "Bearer {{apiKey}}"
    },
    body: {
      "status": "{{status}}",
      "notes": "{{notes}}",
      "nextFollowUp": "{{followUpDate}}"
    },
    variables: [
      {
        name: "status",
        description: "New lead status: qualified, nurturing, or closed",
        type: "string",
        required: true
      },
      {
        name: "notes",
        description: "Notes from the conversation",
        type: "string",
        required: true
      }
    ]
  }
}

CRM Synchronization

Sync lead data with your CRM:

{
  name: "Sync to Salesforce",
  slug: "sync_to_salesforce",
  structure: {
    url: "https://api.salesforce.com/services/data/v58.0/sobjects/Lead/{{leadId}}",
    method: "PATCH",
    headers: {
      "Authorization": "Bearer {{salesforceToken}}",
      "Content-Type": "application/json"
    },
    body: {
      "LastActivityDate": "{{timestamp}}",
      "Description": "{{callSummary}}",
      "Status": "{{newStatus}}",
      "LeadSource": "Voice AI Agent"
    }
  }
}

Best Practices

Lead Data Management

Consistent naming - Use standard field names across all leads
Data validation - Validate phone numbers and emails
Regular cleanup - Remove or archive inactive leads
Privacy compliance - Follow GDPR, CCPA regulations
DNC respect - Honor do-not-contact requests immediately

Memory Management

Store meaningful information - Only important details
Be specific - “Budget: $50K approved for Q1” vs “Has budget”
Time-bound data - Include dates for time-sensitive information
Avoid redundancy - Don’t duplicate the same memory
Regular review - Clean outdated memories periodically

Personalization

Natural references - Mention past conversations naturally
Progressive profiling - Learn more each interaction
Respect context - Don’t ask for already-known information
Update regularly - Keep lead data current
Segment appropriately - Group leads by relevant characteristics

Privacy & Compliance

Consent tracking - Record when/how consent was obtained
Data minimization - Collect only necessary information
Secure storage - Protect sensitive lead data
Right to deletion - Enable lead data deletion
Transparent usage - Be clear about how data is used

Integration Patterns

CRM Integration

Bidirectional sync with your CRM:

// Pull lead data from CRM before call
const crmLead = await fetchFromCRM(leadId);

// Dispatch agent with CRM data
await dispatchAgent({
  leadId: leadId,
  customData: {
    ...crmLead,
    lastCRMUpdate: new Date().toISOString()
  }
});

// Push call results back to CRM after call
await updateCRM(leadId, {
  lastCallDate: callEndTime,
  callDisposition: disposition,
  callNotes: summary
});

Marketing Automation

Trigger marketing actions based on lead interactions:

// After successful qualification call
if (callDisposition === "QUALIFIED") {
  await triggerMarketingWorkflow({
    leadId: leadId,
    workflow: "qualified-lead-nurture",
    data: {
      qualificationDate: now,
      interests: extractedInterests,
      nextStep: "send-proposal"
    }
  });
}

Common Use Cases

Sales Qualification

Score and qualify leads through AI conversations

Customer Support

Provide personalized support with conversation history

Appointment Setting

Schedule meetings with context from previous interactions

Lead Nurturing

Warm up leads over time with multi-touch campaigns

Re-engagement

Win back inactive leads with personalized outreach

Survey & Feedback

Collect feedback with context about customer journey

Troubleshooting

Missing Lead Data

Check:

Lead ID is correct
Lead exists in organization
Permissions are properly set
Data was synced from source system

Memories Not Appearing

Verify:

Agent is configured to create memories
Conversation completed successfully
Memory creation prompt is clear
Call wasn’t interrupted

Outdated Lead Information

Solutions:

Implement regular CRM sync
Update lead data before calls
Add data freshness checks
Archive stale leads

Next Steps

Agents

Configure agents to use lead context

Workflows

Create multi-touch lead engagement workflows

Tools

Build tools to update lead information

API Reference

Explore the leads API

Getting Started

Core Concepts

​What Are Leads?

​Lead Structure

​Basic Lead Information

​Conversation Memories

​Managing Leads

​Listing All Leads

​Viewing Lead Memories

​Leads in Agent Conversations

​Memory Creation

​Memory Recall

​Configuring Memory in Agents

​Leads in Workflows

​Workflow Executions

​Lead Variables in Workflows

​Leads in Dispatches

​Agent Dispatch with Lead Context

​Custom Fields and Metadata

​Structuring Lead Data

​Using Custom Fields in Conversations

​Lead Lifecycle

​Lead States

​Conversation Context

​Building Context Over Time

​Memory-Driven Personalization

​Lead Tools Integration

​Updating Leads During Calls

​CRM Synchronization

​Best Practices

​Lead Data Management

​Memory Management

​Personalization

​Privacy & Compliance

​Integration Patterns

​CRM Integration

​Marketing Automation

​Common Use Cases