Best Keap (Infusionsoft) Phone Validation API & Email Verification Integration 2025

// Keap API integration with phone validation
const keapClient = require('keap-sdk');
const fetch = require('node-fetch');

class KeapValidationIntegration {
  constructor(keapAccessToken, lookupApiKey) {
    this.keap = new keapClient.Client(keapAccessToken);
    this.lookupApiKey = lookupApiKey;
  }
  
  async validateAndCreateContact(contactData) {
    try {
      // Validate phone and email before creating contact
      const validation = await this.validateContactInfo(contactData);
      
      // Create contact in Keap with validation results
      const contact = await this.keap.contacts.create({
        given_name: contactData.firstName,
        family_name: contactData.lastName,
        email_addresses: validation.email?.isValid ? 
          [{ email: contactData.email, field: 'EMAIL1' }] : [],
        phone_numbers: validation.phone?.isValid ? 
          [{ number: contactData.phone, field: 'PHONE1' }] : [],
        custom_fields: [
          { content: validation.phone?.isValid ? 'Valid' : 'Invalid', id: 'phone_validation_status' },
          { content: validation.phone?.carrier || '', id: 'phone_carrier' },
          { content: validation.phone?.riskLevel || 'Unknown', id: 'phone_risk_level' },
          { content: validation.email?.isValid ? 'Valid' : 'Invalid', id: 'email_validation_status' }
        ]
      });
      
      // Apply tags based on validation results
      await this.applyValidationTags(contact.id, validation);
      
      return { success: true, contactId: contact.id, validation };
      
    } catch (error) {
      console.error('Keap contact creation failed:', error);
      return { success: false, error: error.message };
    }
  }
  
  async validateContactInfo(contactData) {
    const results = {};
    
    // Validate phone number
    if (contactData.phone) {
      const phoneResponse = await fetch('https://app.1lookup.io/api/v1/phone', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.lookupApiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ phone: contactData.phone })
      });
      
      const phoneData = await phoneResponse.json();
      results.phone = {
        isValid: phoneData.data.classification.is_valid,
        carrier: phoneData.data.carrier_details?.name,
        lineType: phoneData.data.carrier_details?.type,
        riskLevel: phoneData.data.risk_assessment?.risk_level,
        location: phoneData.data.location_details?.city
      };
    }
    
    // Validate email address
    if (contactData.email) {
      const emailResponse = await fetch('https://app.1lookup.io/api/v1/email', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.lookupApiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ email: contactData.email })
      });
      
      const emailData = await emailResponse.json();
      results.email = {
        isValid: emailData.data.classification.is_valid,
        deliverable: emailData.data.classification.deliverable,
        riskLevel: emailData.data.risk_assessment?.risk_level
      };
    }
    
    return results;
  }
  
  async applyValidationTags(contactId, validation) {
    const tags = [];
    
    // Phone validation tags
    if (validation.phone) {
      if (validation.phone.isValid) {
        tags.push({ id: 'phone_validated' });
        
        if (validation.phone.riskLevel === 'Low') {
          tags.push({ id: 'high_quality_phone' });
        }
        
        if (validation.phone.lineType === 'mobile') {
          tags.push({ id: 'mobile_user' });
        }
      } else {
        tags.push({ id: 'invalid_phone' });
      }
    }
    
    // Email validation tags
    if (validation.email) {
      if (validation.email.isValid && validation.email.deliverable) {
        tags.push({ id: 'email_validated' });
      } else {
        tags.push({ id: 'email_issues' });
      }
    }
    
    // Apply tags to contact
    if (tags.length > 0) {
      await this.keap.contacts.addTags(contactId, tags);
    }
  }
}

// Usage
const keapIntegration = new KeapValidationIntegration(
  process.env.KEAP_ACCESS_TOKEN,
  process.env.LOOKUP_API_KEY
);

const result = await keapIntegration.validateAndCreateContact({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  phone: '+1234567890'
});

// Campaign-based validation integration
async function validateCampaignContacts(campaignId) {
  try {
    // Get all contacts in campaign
    const contacts = await keap.campaigns.getContacts(campaignId);
    
    let validatedCount = 0;
    let invalidCount = 0;
    
    for (const contact of contacts) {
      // Validate each contact
      const validation = await validateContactInfo({
        phone: contact.phone_numbers?.[0]?.number,
        email: contact.email_addresses?.[0]?.email
      });
      
      // Calculate quality score
      const qualityScore = calculateQualityScore(validation);
      
      // Update contact with validation results
      await keap.contacts.update(contact.id, {
        custom_fields: [
          { id: 'validation_score', content: qualityScore.toString() },
          { id: 'phone_validation_status', content: validation.phone?.isValid ? 'Valid' : 'Invalid' },
          { id: 'email_validation_status', content: validation.email?.isValid ? 'Valid' : 'Invalid' }
        ]
      });
      
      // Move to appropriate campaign sequence
      if (qualityScore >= 75) {
        await keap.campaigns.addContactToSequence(contact.id, 'high_quality_sequence');
        validatedCount++;
      } else {
        await keap.campaigns.addContactToSequence(contact.id, 'nurture_sequence');
        invalidCount++;
      }
    }
    
    return { validated: validatedCount, invalid: invalidCount };
    
  } catch (error) {
    console.error('Campaign validation failed:', error);
    throw error;
  }
}

function calculateQualityScore(validation) {
  let score = 0;
  
  // Phone validation scoring
  if (validation.phone?.isValid) {
    score += 50;
    if (validation.phone.riskLevel === 'Low') score += 25;
    if (validation.phone.lineType === 'mobile') score += 15;
  }
  
  // Email validation scoring
  if (validation.email?.isValid && validation.email.deliverable) {
    score += 35;
    if (validation.email.riskLevel === 'Low') score += 10;
  }
  
  return Math.min(100, score);
}

// Advanced Keap campaign optimization with validation
class KeapCampaignOptimizer {
  constructor(keapClient, lookupApiKey) {
    this.keap = keapClient;
    this.lookupApiKey = lookupApiKey;
    
    // Campaign segment definitions
    this.segments = {
      premium: { minScore: 85, sequenceId: 'seq_premium_001' },
      standard: { minScore: 60, sequenceId: 'seq_standard_002' },
      nurture: { minScore: 35, sequenceId: 'seq_nurture_003' },
      cleanup: { minScore: 0, sequenceId: 'seq_cleanup_004' }
    };
  }
  
  async optimizeCampaign(campaignId) {
    try {
      const contacts = await this.keap.campaigns.getContacts(campaignId);
      const results = {
        processed: 0,
        segmented: { premium: 0, standard: 0, nurture: 0, cleanup: 0 },
        errors: []
      };
      
      for (const contact of contacts) {
        try {
          // Get contact validation data
          const validation = await this.getContactValidation(contact);
          
          // Calculate comprehensive quality score
          const qualityScore = this.calculateAdvancedScore(validation, contact);
          
          // Determine optimal segment
          const segment = this.determineSegment(qualityScore);
          
          // Update contact with enhanced data
          await this.updateContactWithValidation(contact.id, validation, qualityScore, segment);
          
          // Move to appropriate campaign sequence
          await this.moveToSegmentSequence(contact.id, segment);
          
          // Apply behavioral tags
          await this.applyBehavioralTags(contact.id, validation, segment);
          
          results.processed++;
          results.segmented[segment]++;
          
        } catch (error) {
          results.errors.push(`Contact ${contact.id}: ${error.message}`);
        }
      }
      
      return results;
      
    } catch (error) {
      throw new Error(`Campaign optimization failed: ${error.message}`);
    }
  }
  
  calculateAdvancedScore(validation, contact) {
    let score = 0;
    let factors = [];
    
    // Phone validation scoring (40 points max)
    if (validation.phone) {
      if (validation.phone.isValid) {
        score += 25;
        factors.push('Valid Phone');
        
        // Risk level bonus/penalty
        switch (validation.phone.riskLevel) {
          case 'Low': 
            score += 15; 
            factors.push('Low Phone Risk');
            break;
          case 'Medium': 
            score += 8;
            break;
          case 'High': 
            score -= 5;
            factors.push('High Phone Risk');
            break;
        }
        
        // Line type bonus
        if (validation.phone.lineType === 'mobile') {
          score += 10;
          factors.push('Mobile Phone');
        }
        
        // Carrier reliability (if known)
        if (validation.phone.carrier && this.isReliableCarrier(validation.phone.carrier)) {
          score += 5;
          factors.push('Reliable Carrier');
        }
      } else {
        score -= 15;
        factors.push('Invalid Phone');
      }
    }
    
    // Email validation scoring (35 points max)
    if (validation.email) {
      if (validation.email.isValid) {
        score += 20;
        factors.push('Valid Email');
        
        if (validation.email.deliverable) {
          score += 10;
          factors.push('Deliverable Email');
        }
        
        // Domain reputation
        if (validation.email.domainReputation === 'High') {
          score += 8;
          factors.push('High Domain Rep');
        }
        
        // Risk assessment
        if (validation.email.riskLevel === 'Low') {
          score += 7;
          factors.push('Low Email Risk');
        }
      } else {
        score -= 10;
        factors.push('Invalid Email');
      }
    }
    
    // Engagement history bonus (25 points max)
    const engagementScore = this.calculateEngagementScore(contact);
    score += engagementScore;
    if (engagementScore > 0) {
      factors.push(`Engagement: ${engagementScore}pts`);
    }
    
    return {
      total: Math.max(0, Math.min(100, score)),
      factors: factors
    };
  }
  
  calculateEngagementScore(contact) {
    let engagementScore = 0;
    
    // Email engagement
    if (contact.last_email_click) {
      const daysSinceClick = this.getDaysAgo(contact.last_email_click);
      if (daysSinceClick < 7) engagementScore += 15;
      else if (daysSinceClick < 30) engagementScore += 10;
      else if (daysSinceClick < 90) engagementScore += 5;
    }
    
    // Website activity
    if (contact.last_website_visit) {
      const daysSinceVisit = this.getDaysAgo(contact.last_website_visit);
      if (daysSinceVisit < 7) engagementScore += 10;
      else if (daysSinceVisit < 30) engagementScore += 6;
    }
    
    // Purchase history
    if (contact.lifetime_value > 0) {
      if (contact.lifetime_value > 1000) engagementScore += 20;
      else if (contact.lifetime_value > 500) engagementScore += 15;
      else engagementScore += 10;
    }
    
    return Math.min(25, engagementScore);
  }
  
  determineSegment(qualityScore) {
    const score = qualityScore.total;
    
    if (score >= this.segments.premium.minScore) return 'premium';
    if (score >= this.segments.standard.minScore) return 'standard';
    if (score >= this.segments.nurture.minScore) return 'nurture';
    return 'cleanup';
  }
  
  async moveToSegmentSequence(contactId, segment) {
    const sequenceId = this.segments[segment].sequenceId;
    
    try {
      // Remove from all other sequences first
      await this.keap.campaigns.removeFromAllSequences(contactId);
      
      // Add to appropriate sequence
      await this.keap.campaigns.addToSequence(contactId, sequenceId);
      
    } catch (error) {
      console.error(`Failed to move contact ${contactId} to segment ${segment}:, error);
    }
  }
  
  async applyBehavioralTags(contactId, validation, segment) {
    const tags = [`segment_${segment}`];
    
    // Validation-based tags
    if (validation.phone?.isValid) {
      tags.push('phone_validated');
      
      if (validation.phone.lineType === 'mobile') {
        tags.push('mobile_user', 'sms_eligible');
      }
      
      if (validation.phone.riskLevel === 'Low') {
        tags.push('high_quality_contact');
      }
    }
    
    if (validation.email?.isValid && validation.email.deliverable) {
      tags.push('email_validated', 'email_marketing_safe');
    }
    
    // Segment-specific tags
    switch (segment) {
      case 'premium':
        tags.push('vip_treatment', 'priority_support', 'upsell_eligible');
        break;
      case 'standard':
        tags.push('regular_customer', 'newsletter_subscriber');
        break;
      case 'nurture':
        tags.push('needs_nurturing', 'educational_content');
        break;
      case 'cleanup':
        tags.push('data_cleanup_needed', 'low_quality');
        break;
    }
    
    // Apply all tags
    try {
      await this.keap.contacts.addTags(contactId, tags.map(tag => ({ id: tag })));
    } catch (error) {
      console.error(`Failed to apply tags to contact ${contactId}:, error);
    }
  }
  
  isReliableCarrier(carrier) {
    const reliableCarriers = ['Verizon', 'AT&T', 'T-Mobile', 'Sprint'];
    return reliableCarriers.includes(carrier);
  }
  
  getDaysAgo(dateString) {
    const date = new Date(dateString);
    const now = new Date();
    return Math.floor((now - date) / (1000 * 60 * 60 * 24));
  }
}

// Usage example
const campaignOptimizer = new KeapCampaignOptimizer(keapClient, lookupApiKey);
const results = await campaignOptimizer.optimizeCampaign('campaign_123');
console.log('Campaign optimization results:', results);