Best Nutshell CRM Phone Validation API & Email Verification Integration 2025

// Nutshell CRM API integration with phone validation and reporting
const NutshellClient = require('nutshell-crm-api');
const fetch = require('node-fetch');

class NutshellValidationIntegration {
  constructor(nutshellConfig, lookupApiKey) {
    this.nutshell = new NutshellClient({
      username: nutshellConfig.username,
      apiKey: nutshellConfig.apiKey,
      domain: nutshellConfig.domain
    });
    this.lookupApiKey = lookupApiKey;
  }
  
  async createValidatedContact(contactData) {
    try {
      // Validate contact information for reporting accuracy
      const validation = await this.validateContactInfo(contactData);
      
      // Calculate comprehensive quality metrics for reporting
      const qualityMetrics = this.calculateQualityMetrics(validation);
      
      // Create contact in Nutshell CRM with validation data
      const contact = await this.nutshell.contacts.create({
        name: contactData.name,
        email: validation.email?.isValid ? contactData.email : null,
        phone: validation.phone?.isValid ? contactData.phone : null,
        company: contactData.company,
        description: contactData.description,
        customFields: {
          'validation_status': validation.phone?.isValid && validation.email?.isValid ? 'Fully Validated' : 'Partial',
          'phone_validation_result': validation.phone?.isValid ? 'Valid' : 'Invalid',
          'phone_carrier': validation.phone?.carrier || '',
          'phone_line_type': validation.phone?.lineType || '',
          'phone_risk_assessment': validation.phone?.riskLevel || 'Unknown',
          'phone_location': validation.phone?.location || '',
          'email_validation_result': validation.email?.isValid ? 'Valid' : 'Invalid',
          'email_deliverability': validation.email?.deliverable ? 'Deliverable' : 'Not Deliverable',
          'email_risk_assessment': validation.email?.riskLevel || 'Unknown',
          'contact_quality_score': qualityMetrics.overallScore,
          'data_freshness_score': qualityMetrics.freshnessScore,
          'validation_timestamp': new Date().toISOString(),
          'reporting_segment': this.determineReportingSegment(qualityMetrics)
        }
      });
      
      // Create associated lead with validation insights
      const lead = await this.nutshell.leads.create({
        contactId: contact.id,
        description: `Lead from ${contactData.name} - Quality Score: ${qualityMetrics.overallScore}`,
        confidence: this.mapQualityToConfidence(qualityMetrics.overallScore),
        value: this.estimateLeadValue(qualityMetrics),
        customFields: {
          'lead_quality_indicators': this.generateQualityIndicators(validation),
          'expected_conversion_probability': qualityMetrics.conversionProbability,
          'recommended_follow_up_method': this.recommendFollowUpMethod(validation),
          'data_quality_flags': this.generateDataQualityFlags(validation)
        }
      });
      
      // Schedule automated follow-up based on validation results
      await this.scheduleValidationBasedFollowUp(contact.id, lead.id, validation, qualityMetrics);
      
      // Update reporting metrics
      await this.updateReportingMetrics(validation, qualityMetrics);
      
      return {
        success: true,
        contactId: contact.id,
        leadId: lead.id,
        qualityMetrics: qualityMetrics,
        reportingSegment: this.determineReportingSegment(qualityMetrics),
        validation: validation
      };
      
    } catch (error) {
      console.error('Nutshell CRM contact creation failed:', error);
      return { success: false, error: error.message };
    }
  }
  
  async validateContactInfo(contactData) {
    const results = {};
    
    // Advanced phone validation with reporting metrics
    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,
          include_carrier_details: true,
          include_location_details: true,
          include_risk_assessment: true
        })
      });
      
      if (phoneResponse.ok) {
        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,
          networkType: phoneData.data.carrier_details?.network_type,
          riskLevel: phoneData.data.risk_assessment?.risk_level,
          riskScore: phoneData.data.risk_assessment?.risk_score,
          location: phoneData.data.location_details?.city,
          country: phoneData.data.location_details?.country,
          timezone: phoneData.data.location_details?.timezone,
          portabilityStatus: phoneData.data.carrier_details?.portability_status,
          reachabilityConfidence: phoneData.data.classification.reachability_confidence
        };
      }
    }
    
    // Advanced email validation with deliverability metrics
    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,
          include_domain_details: true,
          include_risk_assessment: true,
          include_deliverability_check: true
        })
      });
      
      if (emailResponse.ok) {
        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,
          riskScore: emailData.data.risk_assessment?.risk_score,
          domain: emailData.data.domain_details?.domain,
          domainAge: emailData.data.domain_details?.age_days,
          domainReputation: emailData.data.domain_details?.reputation,
          emailType: emailData.data.classification.email_type,
          spamScore: emailData.data.risk_assessment?.spam_score,
          deliverabilityConfidence: emailData.data.classification.deliverability_confidence
        };
      }
    }
    
    return results;
  }
  
  calculateQualityMetrics(validation) {
    let overallScore = 0;
    let componentScores = {};
    
    // Phone validation scoring with detailed breakdown
    if (validation.phone) {
      let phoneScore = 0;
      
      if (validation.phone.isValid) {
        phoneScore += 40; // Base validity score
        
        // Risk level impact
        switch (validation.phone.riskLevel) {
          case 'Low': phoneScore += 25; break;
          case 'Medium': phoneScore += 15; break;
          case 'High': phoneScore -= 10; break;
        }
        
        // Line type preference (mobile generally better for outreach)
        if (validation.phone.lineType === 'mobile') {
          phoneScore += 20;
        } else if (validation.phone.lineType === 'landline') {
          phoneScore += 15;
        }
        
        // Carrier reliability bonus
        if (validation.phone.carrier && this.isReliableCarrier(validation.phone.carrier)) {
          phoneScore += 10;
        }
        
        // Reachability confidence
        if (validation.phone.reachabilityConfidence >= 0.8) {
          phoneScore += 15;
        } else if (validation.phone.reachabilityConfidence >= 0.6) {
          phoneScore += 10;
        }
        
        // Network type consideration
        if (validation.phone.networkType === '4G' || validation.phone.networkType === '5G') {
          phoneScore += 5;
        }
        
      } else {
        phoneScore -= 25; // Penalty for invalid phone
      }
      
      componentScores.phone = Math.max(0, Math.min(100, phoneScore));
      overallScore += componentScores.phone * 0.6; // 60% weight for phone
    }
    
    // Email validation scoring with deliverability focus
    if (validation.email) {
      let emailScore = 0;
      
      if (validation.email.isValid) {
        emailScore += 30; // Base validity score
        
        // Deliverability is crucial for reporting accuracy
        if (validation.email.deliverable) {
          emailScore += 25;
          
          // Deliverability confidence bonus
          if (validation.email.deliverabilityConfidence >= 0.9) {
            emailScore += 15;
          } else if (validation.email.deliverabilityConfidence >= 0.7) {
            emailScore += 10;
          }
        }
        
        // Risk assessment
        switch (validation.email.riskLevel) {
          case 'Low': emailScore += 15; break;
          case 'Medium': emailScore += 8; break;
          case 'High': emailScore -= 5; break;
        }
        
        // Domain age and reputation
        if (validation.email.domainAge > 365) {
          emailScore += 10; // Established domain
        }
        
        if (validation.email.domainReputation === 'High') {
          emailScore += 8;
        } else if (validation.email.domainReputation === 'Medium') {
          emailScore += 4;
        }
        
        // Spam score consideration
        if (validation.email.spamScore < 0.3) {
          emailScore += 7;
        } else if (validation.email.spamScore > 0.7) {
          emailScore -= 10;
        }
        
      } else {
        emailScore -= 20; // Penalty for invalid email
      }
      
      componentScores.email = Math.max(0, Math.min(100, emailScore));
      overallScore += componentScores.email * 0.4; // 40% weight for email
    }
    
    // Calculate additional metrics for reporting
    const freshnessScore = this.calculateDataFreshnessScore();
    const conversionProbability = this.estimateConversionProbability(overallScore, validation);
    
    return {
      overallScore: Math.round(overallScore),
      componentScores: componentScores,
      freshnessScore: freshnessScore,
      conversionProbability: conversionProbability,
      validationTimestamp: new Date().toISOString(),
      dataIntegrityScore: this.calculateDataIntegrityScore(validation)
    };
  }
  
  determineReportingSegment(qualityMetrics) {
    const score = qualityMetrics.overallScore;
    
    if (score >= 85) return 'Premium Prospects';
    if (score >= 70) return 'High Quality Leads';
    if (score >= 55) return 'Standard Contacts';
    if (score >= 40) return 'Nurture Required';
    if (score >= 25) return 'Data Review Needed';
    return 'Cleanup Required';
  }
  
  recommendFollowUpMethod(validation) {
    const methods = [];
    
    if (validation.phone?.isValid && validation.phone.riskLevel === 'Low') {
      if (validation.phone.lineType === 'mobile') {
        methods.push('SMS', 'Voice Call');
      } else {
        methods.push('Voice Call');
      }
    }
    
    if (validation.email?.isValid && validation.email.deliverable && validation.email.riskLevel === 'Low') {
      methods.push('Email Marketing', 'Email Sequence');
    }
    
    if (methods.length === 0) {
      methods.push('Manual Research', 'Data Update');
    }
    
    return methods.join(', ');
  }
  
  generateQualityIndicators(validation) {
    const indicators = [];
    
    if (validation.phone?.isValid) {
      indicators.push(`✓ Valid Phone (${validation.phone.carrier})`);
      
      if (validation.phone.riskLevel === 'Low') {
        indicators.push('✓ Low Risk Phone');
      }
      
      if (validation.phone.lineType === 'mobile') {
        indicators.push('✓ Mobile Contact');
      }
    } else if (validation.phone) {
      indicators.push('✗ Invalid Phone Number');
    }
    
    if (validation.email?.isValid && validation.email.deliverable) {
      indicators.push('✓ Deliverable Email');
      
      if (validation.email.riskLevel === 'Low') {
        indicators.push('✓ Low Risk Email');
      }
    } else if (validation.email) {
      indicators.push('✗ Email Issues Detected');
    }
    
    return indicators.join(' | ');
  }
  
  async scheduleValidationBasedFollowUp(contactId, leadId, validation, qualityMetrics) {
    const activities = [];
    const score = qualityMetrics.overallScore;
    
    // High quality contacts get immediate attention
    if (score >= 80) {
      activities.push({
        type: 'Call',
        contactId: contactId,
        leadId: leadId,
        dueDate: new Date(Date.now() + 2 * 60 * 60 * 1000), // 2 hours
        note: `High-quality prospect (Score: ${score}) - Priority follow-up`,
        priority: 'High'
      });
    }
    
    // Medium quality get email outreach
    else if (score >= 60) {
      activities.push({
        type: 'Email',
        contactId: contactId,
        leadId: leadId,
        dueDate: new Date(Date.now() + 6 * 60 * 60 * 1000), // 6 hours
        note: `Quality prospect (Score: ${score}) - Email outreach`,
        priority: 'Medium'
      });
    }
    
    // Lower quality need research
    else {
      activities.push({
        type: 'Task',
        contactId: contactId,
        leadId: leadId,
        dueDate: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
        note: `Research needed (Score: ${score}) - Verify and update contact info`,
        priority: 'Low'
      });
    }
    
    // Create activities in Nutshell
    for (const activity of activities) {
      await this.nutshell.activities.create(activity);
    }
  }
  
  // Helper methods
  isReliableCarrier(carrier) {
    const reliableCarriers = [
      'Verizon', 'AT&T', 'T-Mobile', 'Sprint', 'US Cellular',
      'Bell', 'Rogers', 'Telus', 'Vodafone', 'O2'
    ];
    return reliableCarriers.includes(carrier);
  }
  
  calculateDataFreshnessScore() {
    // Base score - can be enhanced with actual data age if available
    return 85 + Math.floor(Math.random() * 15); // 85-100 range
  }
  
  estimateConversionProbability(overallScore, validation) {
    let probability = overallScore * 0.8; // Base conversion correlation
    
    // Adjustments based on specific validation results
    if (validation.phone?.lineType === 'mobile' && validation.email?.deliverable) {
      probability += 10;
    }
    
    if (validation.phone?.riskLevel === 'Low' && validation.email?.riskLevel === 'Low') {
      probability += 15;
    }
    
    return Math.min(100, Math.max(0, Math.round(probability)));
  }
  
  calculateDataIntegrityScore(validation) {
    let score = 100;
    
    if (validation.phone && !validation.phone.isValid) score -= 30;
    if (validation.email && !validation.email.isValid) score -= 25;
    if (validation.phone?.riskLevel === 'High') score -= 15;
    if (validation.email?.riskLevel === 'High') score -= 10;
    
    return Math.max(0, score);
  }
  
  generateDataQualityFlags(validation) {
    const flags = [];
    
    if (validation.phone?.riskLevel === 'High') {
      flags.push('HIGH_PHONE_RISK');
    }
    
    if (validation.email?.riskLevel === 'High') {
      flags.push('HIGH_EMAIL_RISK');
    }
    
    if (!validation.phone?.isValid && !validation.email?.isValid) {
      flags.push('NO_VALID_CONTACT_METHOD');
    }
    
    if (validation.email?.spamScore > 0.7) {
      flags.push('HIGH_SPAM_RISK');
    }
    
    return flags.length > 0 ? flags.join(',') : 'CLEAN';
  }
  
  mapQualityToConfidence(qualityScore) {
    if (qualityScore >= 85) return 10; // Very High
    if (qualityScore >= 70) return 8;  // High
    if (qualityScore >= 55) return 6;  // Medium
    if (qualityScore >= 40) return 4;  // Low
    return 2; // Very Low
  }
  
  estimateLeadValue(qualityMetrics) {
    const baseValue = 1000;
    const multiplier = qualityMetrics.overallScore / 100;
    const conversionBonus = qualityMetrics.conversionProbability * 50;
    
    return Math.round(baseValue * multiplier + conversionBonus);
  }
  
  async updateReportingMetrics(validation, qualityMetrics) {
    // Update internal metrics for reporting dashboard
    // This would integrate with your reporting system
    const metrics = {
      totalValidationsToday: 1,
      validPhoneRate: validation.phone?.isValid ? 1 : 0,
      validEmailRate: validation.email?.isValid ? 1 : 0,
      averageQualityScore: qualityMetrics.overallScore,
      timestamp: new Date().toISOString()
    };
    
    // Store or update metrics as needed
    console.log('Updated reporting metrics:', metrics);
  }
}

// Usage example
const nutshellIntegration = new NutshellValidationIntegration({
  username: process.env.NUTSHELL_USERNAME,
  apiKey: process.env.NUTSHELL_API_KEY,
  domain: process.env.NUTSHELL_DOMAIN
}, process.env.LOOKUP_API_KEY);

// Create a validated contact with comprehensive reporting
const result = await nutshellIntegration.createValidatedContact({
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890',
  company: 'Acme Corp',
  description: 'Potential client from trade show'
});

console.log('Contact creation result:', result);