Best Segment Customer Data Platform Phone Validation API & Email Verification Integration 2025

// Segment Source Function for real-time contact validation
async function onTrack(event, settings) {
  // Initialize 1lookup API client
  const lookupApiKey = settings.lookupApiKey;
  
  try {
    // Extract contact information from event properties
    const contactInfo = extractContactInfo(event);
    
    if (contactInfo.phone || contactInfo.email) {
      // Validate contact information
      const validationData = await validateContactWithSegment(contactInfo, lookupApiKey);
      
      // Enhance event properties with validation results
      event.properties = {
        ...event.properties,
        // Phone validation enhancement
        phone_validation_status: validationData.phone?.is_valid,
        phone_carrier: validationData.phone?.carrier_details?.name,
        phone_line_type: validationData.phone?.carrier_details?.type,
        phone_country: validationData.phone?.location_details?.country,
        phone_region: validationData.phone?.location_details?.region,
        phone_risk_level: validationData.phone?.risk_assessment?.risk_level,
        // Email validation enhancement  
        email_validation_status: validationData.email?.is_valid,
        email_deliverability: validationData.email?.deliverability?.status,
        email_domain_type: validationData.email?.domain_details?.type,
        email_risk_level: validationData.email?.risk_assessment?.risk_level,
        // Combined customer quality metrics
        customer_quality_score: calculateCustomerQualityScore(validationData),
        customer_quality_tier: determineCustomerTier(validationData),
        is_high_quality_customer: isHighQualityCustomer(validationData),
        validation_timestamp: new Date().toISOString(),
        // Segment-specific enhancements
        segment_validation_version: '2025.1',
        cross_platform_quality_score: calculateCrossPlatformScore(validationData)
      };
      
      // Add validation traits to user profile
      event.context.traits = {
        ...event.context.traits,
        contact_quality_score: event.properties.customer_quality_score,
        customer_quality_tier: event.properties.customer_quality_tier,
        last_validation_date: event.properties.validation_timestamp
      };
    }
    
    return event;
    
  } catch (error) {
    console.error('Segment validation error:', error);
    // Add error tracking without breaking the pipeline
    event.properties.validation_error = true;
    event.properties.validation_error_message = error.message;
    return event;
  }
}

// Contact validation function optimized for Segment
async function validateContactWithSegment(contactInfo, apiKey) {
  const response = await fetch('https://app.1lookup.io/api/v1/validate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'X-Integration': 'segment-cdp'
    },
    body: JSON.stringify({
      ...contactInfo,
      include_carrier_details: true,
      include_location_details: true,
      include_risk_assessment: true
    })
  });
  
  if (!response.ok) {
    throw new Error(`Validation failed: ${response.status}`);
  }
  
  return await response.json();
}

// Extract contact information from various event types
function extractContactInfo(event) {
  const contactInfo = {};
  
  // Check event properties
  if (event.properties.phone) contactInfo.phone = event.properties.phone;
  if (event.properties.email) contactInfo.email = event.properties.email;
  
  // Check user traits
  if (event.context?.traits?.phone) contactInfo.phone = event.context.traits.phone;
  if (event.context?.traits?.email) contactInfo.email = event.context.traits.email;
  
  // Check for nested contact objects
  if (event.properties.contact?.phone) contactInfo.phone = event.properties.contact.phone;
  if (event.properties.contact?.email) contactInfo.email = event.properties.contact.email;
  
  return contactInfo;
}

// Segment Destination Function for customer profile enhancement
async function onIdentify(event, settings) {
  const lookupApiKey = settings.lookupApiKey;
  
  try {
    // Extract customer contact information
    const customerData = {
      phone: event.traits.phone || event.properties.phone,
      email: event.traits.email || event.properties.email
    };
    
    if (customerData.phone || customerData.email) {
      // Validate customer contact information
      const validation = await validateCustomerProfile(customerData, lookupApiKey);
      
      // Enhance customer traits with validation insights
      const enhancedTraits = {
        ...event.traits,
        // Contact validation traits
        phone_validation_status: validation.phone?.is_valid ? 'Valid' : 'Invalid',
        phone_carrier: validation.phone?.carrier_details?.name || '',
        phone_line_type: validation.phone?.carrier_details?.type || '',
        phone_country: validation.phone?.location_details?.country || '',
        phone_risk_level: validation.phone?.risk_assessment?.risk_level || '',
        email_validation_status: validation.email?.is_valid ? 'Valid' : 'Invalid',
        email_deliverability: validation.email?.deliverability?.status || '',
        email_domain_reputation: validation.email?.domain_details?.reputation || '',
        email_risk_level: validation.email?.risk_assessment?.risk_level || '',
        // Customer quality analytics
        customer_quality_score: calculateUnifiedQualityScore(validation),
        customer_tier: determineCustomerTier(validation),
        is_verified_customer: isVerifiedCustomer(validation),
        fraud_risk_indicators: extractFraudRiskIndicators(validation),
        customer_lifetime_value_tier: predictLTVTier(validation),
        // Cross-platform insights
        cross_destination_quality_score: calculateCrossDestinationScore(validation),
        last_contact_validation: new Date().toISOString(),
        validation_data_freshness: 'real-time'
      };
      
      // Update event with enhanced traits
      event.traits = enhancedTraits;
      
      // Add custom context for downstream destinations
      event.context.customer_validation = {
        quality_score: enhancedTraits.customer_quality_score,
        tier: enhancedTraits.customer_tier,
        is_verified: enhancedTraits.is_verified_customer,
        validation_confidence: calculateValidationConfidence(validation)
      };
    }
    
    return event;
    
  } catch (error) {
    console.error('Customer profile validation error:', error);
    // Maintain data flow with error tracking
    event.traits.validation_error = true;
    event.traits.validation_error_timestamp = new Date().toISOString();
    return event;
  }
}

// Calculate unified quality score for customer profiles
function calculateUnifiedQualityScore(validation) {
  let score = 0;
  
  // Phone validation scoring
  if (validation.phone?.is_valid) score += 40;
  if (validation.phone?.risk_assessment?.risk_level === 'low') score += 10;
  if (validation.phone?.carrier_details?.type === 'mobile') score += 5;
  
  // Email validation scoring  
  if (validation.email?.is_valid) score += 35;
  if (validation.email?.deliverability?.status === 'deliverable') score += 10;
  
  return Math.min(100, score);
}

// Determine customer tier based on validation results
function determineCustomerTier(validation) {
  const qualityScore = calculateUnifiedQualityScore(validation);
  
  if (qualityScore >= 85) return 'platinum';
  if (qualityScore >= 70) return 'gold';
  if (qualityScore >= 50) return 'silver';
  return 'bronze';
}

// Advanced customer profile unification with contact validation
class SegmentCustomerProfileUnifier {
  constructor(segmentWriteKey, lookupApiKey) {
    this.analytics = new Analytics(segmentWriteKey);
    this.lookupApiKey = lookupApiKey;
  }
  
  async unifyCustomerProfileWithValidation(userId, profileData) {
    try {
      // Validate all contact points in the profile
      const contactValidation = await this.validateAllContactPoints(profileData);
      
      // Calculate unified customer quality metrics
      const unifiedQuality = this.calculateUnifiedCustomerQuality(contactValidation);
      
      // Create enhanced unified profile
      const unifiedProfile = {
        userId: userId,
        traits: {
          // Original profile data
          ...profileData,
          // Contact validation enhancements
          primary_phone_valid: contactValidation.primary_phone?.is_valid,
          primary_phone_carrier: contactValidation.primary_phone?.carrier_details?.name,
          primary_phone_country: contactValidation.primary_phone?.location_details?.country,
          primary_email_valid: contactValidation.primary_email?.is_valid,
          primary_email_deliverable: contactValidation.primary_email?.deliverability?.status === 'deliverable',
          // Alternative contact validation
          secondary_phone_valid: contactValidation.secondary_phone?.is_valid,
          secondary_email_valid: contactValidation.secondary_email?.is_valid,
          // Unified quality metrics
          unified_customer_quality_score: unifiedQuality.overall_score,
          customer_verification_level: unifiedQuality.verification_level,
          contact_completeness_score: unifiedQuality.completeness_score,
          customer_reachability_score: unifiedQuality.reachability_score,
          // Risk assessment across all contacts
          unified_fraud_risk_level: unifiedQuality.fraud_risk_level,
          has_verified_contact_method: unifiedQuality.has_verified_contact,
          // Customer journey insights
          customer_acquisition_quality: unifiedQuality.acquisition_quality,
          predicted_customer_lifetime_value: unifiedQuality.predicted_ltv,
          customer_engagement_potential: unifiedQuality.engagement_potential
        },
        context: {
          customer_validation: {
            total_contact_points: contactValidation.total_contacts,
            verified_contact_points: contactValidation.verified_contacts,
            validation_confidence: unifiedQuality.validation_confidence,
            last_unified_validation: new Date().toISOString()
          }
        }
      };
      
      // Send unified profile to Segment
      this.analytics.identify(unifiedProfile);
      
      // Track profile unification event
      this.analytics.track('Customer Profile Unified', {
        userId: userId,
        unification_quality_score: unifiedQuality.overall_score,
        verification_level: unifiedQuality.verification_level,
        contact_points_validated: contactValidation.total_contacts,
        profile_completeness: unifiedQuality.completeness_score
      });
      
      return { success: true, unifiedProfile, qualityMetrics: unifiedQuality };
      
    } catch (error) {
      console.error('Profile unification error:', error);
      return { success: false, error: error.message };
    }
  }
  
  async validateAllContactPoints(profileData) {
    const contactPoints = this.extractAllContactPoints(profileData);
    const validationResults = {};
    
    // Validate primary contacts
    if (contactPoints.primary_phone) {
      validationResults.primary_phone = await this.validateContact({
        phone: contactPoints.primary_phone
      });
    }
    
    if (contactPoints.primary_email) {
      validationResults.primary_email = await this.validateContact({
        email: contactPoints.primary_email
      });
    }
    
    // Validate secondary contacts
    if (contactPoints.secondary_phone) {
      validationResults.secondary_phone = await this.validateContact({
        phone: contactPoints.secondary_phone
      });
    }
    
    if (contactPoints.secondary_email) {
      validationResults.secondary_email = await this.validateContact({
        email: contactPoints.secondary_email
      });
    }
    
    // Calculate summary metrics
    validationResults.total_contacts = Object.keys(contactPoints).length;
    validationResults.verified_contacts = Object.values(validationResults)
      .filter(result => result?.phone?.is_valid || result?.email?.is_valid).length;
    
    return validationResults;
  }
  
  calculateUnifiedCustomerQuality(contactValidation) {
    let overallScore = 0;
    let verificationLevel = 'unverified';
    let completenessScore = 0;
    let reachabilityScore = 0;
    
    // Calculate overall quality score
    if (contactValidation.primary_phone?.phone?.is_valid) overallScore += 30;
    if (contactValidation.primary_email?.email?.is_valid) overallScore += 30;
    if (contactValidation.secondary_phone?.phone?.is_valid) overallScore += 20;
    if (contactValidation.secondary_email?.email?.is_valid) overallScore += 20;
    
    // Determine verification level
    const verifiedContacts = contactValidation.verified_contacts || 0;
    if (verifiedContacts >= 3) verificationLevel = 'highly_verified';
    else if (verifiedContacts >= 2) verificationLevel = 'verified';
    else if (verifiedContacts >= 1) verificationLevel = 'partially_verified';
    
    // Calculate completeness and reachability
    completenessScore = (contactValidation.total_contacts / 4) * 100; // Max 4 contact types
    reachabilityScore = (contactValidation.verified_contacts / contactValidation.total_contacts) * 100;
    
    return {
      overall_score: Math.min(100, overallScore),
      verification_level: verificationLevel,
      completeness_score: Math.round(completenessScore),
      reachability_score: Math.round(reachabilityScore),
      validation_confidence: Math.min(95, overallScore + 10),
      has_verified_contact: verifiedContacts > 0,
      fraud_risk_level: this.calculateUnifiedFraudRisk(contactValidation)
    };
  }
}

// Advanced customer journey tracking across all destinations
class SegmentCustomerJourneyTracker {
  constructor(segmentWriteKey, lookupApiKey) {
    this.analytics = new Analytics(segmentWriteKey);
    this.lookupApiKey = lookupApiKey;
    this.customerCache = new Map();
  }
  
  async trackCustomerJourneyWithValidation(userId, journeyEvent, eventProperties) {
    try {
      // Get or create customer validation profile
      let customerValidation = this.customerCache.get(userId);
      if (!customerValidation) {
        customerValidation = await this.getCustomerValidationProfile(userId);
        this.customerCache.set(userId, customerValidation);
      }
      
      // Calculate journey stage quality
      const journeyQuality = this.calculateJourneyStageQuality(
        journeyEvent, 
        customerValidation, 
        eventProperties
      );
      
      // Enhanced customer journey event
      const journeyEventData = {
        userId: userId,
        event: journeyEvent,
        properties: {
          ...eventProperties,
          // Customer validation insights
          customer_quality_score: customerValidation.quality_score,
          customer_tier: customerValidation.tier,
          contact_verification_status: customerValidation.verification_status,
          // Journey-specific analytics
          journey_stage_quality: journeyQuality.stage_quality,
          journey_confidence_score: journeyQuality.confidence_score,
          is_verified_journey_step: journeyQuality.is_verified,
          journey_attribution_weight: journeyQuality.attribution_weight,
          // Cross-destination insights
          destination_quality_score: journeyQuality.destination_score,
          cross_platform_consistency: journeyQuality.platform_consistency,
          // Fraud and risk assessment
          journey_fraud_risk: customerValidation.fraud_risk_level,
          is_trusted_customer_journey: journeyQuality.is_trusted,
          // Geographic and temporal insights
          customer_region: customerValidation.primary_region,
          journey_timestamp: new Date().toISOString(),
          time_since_last_validation: this.calculateTimeSinceValidation(customerValidation)
        },
        context: {
          customer_validation: customerValidation,
          journey_analytics: {
            stage: journeyEvent,
            quality_metrics: journeyQuality,
            validation_confidence: customerValidation.validation_confidence
          }
        }
      };
      
      // Track the enhanced journey event
      this.analytics.track(journeyEventData.event, journeyEventData.properties, {
        context: journeyEventData.context
      });
      
      // Update customer journey profile
      this.updateCustomerJourneyProfile(userId, journeyEvent, journeyQuality);
      
      // Track cross-destination journey analytics
      this.analytics.track('Customer Journey Analytics', {
        userId: userId,
        journey_event: journeyEvent,
        customer_tier: customerValidation.tier,
        stage_quality: journeyQuality.stage_quality,
        cross_destination_impact: journeyQuality.destination_impact
      });
      
    } catch (error) {
      console.error('Customer journey tracking error:', error);
      // Fallback journey tracking
      this.analytics.track(journeyEvent, {
        ...eventProperties,
        validation_error: true,
        error_type: 'journey_validation_failed'
      });
    }
  }
  
  calculateJourneyStageQuality(journeyEvent, customerValidation, eventProps) {
    let stageQuality = 0;
    let confidenceScore = 0;
    
    // Base quality from customer validation
    const baseQuality = customerValidation.quality_score || 0;
    stageQuality = baseQuality * 0.6; // 60% weight
    
    // Journey stage-specific scoring
    const stageMultipliers = {
      'page_viewed': 1.0,
      'product_viewed': 1.1,
      'product_added': 1.3,
      'checkout_started': 1.5,
      'order_completed': 1.8,
      'subscription_started': 2.0,
      'account_created': 1.4,
      'profile_completed': 1.2
    };
    
    stageQuality *= (stageMultipliers[journeyEvent] || 1.0);
    
    // Confidence scoring based on contact verification
    if (customerValidation.phone_verified) confidenceScore += 40;
    if (customerValidation.email_verified) confidenceScore += 40;
    if (customerValidation.fraud_risk_level === 'low') confidenceScore += 20;
    
    // Calculate attribution weight
    const attributionWeight = Math.min(100, stageQuality + confidenceScore) / 100;
    
    return {
      stage_quality: Math.min(100, stageQuality),
      confidence_score: Math.min(100, confidenceScore),
      is_verified: confidenceScore >= 60,
      attribution_weight: attributionWeight,
      is_trusted: customerValidation.fraud_risk_level === 'low' && confidenceScore >= 70,
      destination_score: this.calculateDestinationQualityScore(customerValidation),
      platform_consistency: this.calculatePlatformConsistency(customerValidation)
    };
  }
  
  async getCustomerValidationProfile(userId) {
    // Retrieve customer data from Segment profiles API or cache
    try {
      const customerData = await this.getSegmentProfile(userId);
      
      if (customerData.traits.phone || customerData.traits.email) {
        const validation = await this.validateCustomerContacts({
          phone: customerData.traits.phone,
          email: customerData.traits.email
        });
        
        return {
          quality_score: validation.overall_quality_score,
          tier: this.determineCustomerTier(validation),
          verification_status: this.getVerificationStatus(validation),
          phone_verified: validation.phone?.is_valid,
          email_verified: validation.email?.is_valid,
          fraud_risk_level: validation.fraud_risk_level,
          primary_region: validation.phone?.location_details?.country,
          last_validation: new Date().toISOString(),
          validation_confidence: validation.confidence_score
        };
      }
      
      return { quality_score: 0, tier: 'unverified' };
      
    } catch (error) {
      console.error('Customer profile retrieval error:', error);
      return { quality_score: 0, tier: 'unknown', error: true };
    }
  }
}