How SaaSFlow Reduced Customer Onboarding Time by 78% with Phone Verification

// Enterprise B2B Onboarding Verification System
class EnterpriseOnboardingService {
  constructor() {
    this.phoneCheckClient = new PhoneCheckClient({
      apiKey: process.env.PHONE_CHECK_API_KEY,
      baseURL: 'https://api.phone-check.app',
      timeout: 5000,
      retries: 3
    });
    this.enterpriseEngine = new EnterpriseVerificationEngine();
    this.workflowManager = new MultiUserWorkflowManager();
    this.integrationHub = new B2BIntegrationHub();
  }

  async initiateEnterpriseOnboarding(customerData, stakeholders) {
    const startTime = Date.now();

    try {
      // Step 1: Primary contact verification
      const primaryContactVerification = await this.verifyPrimaryContact(customerData.primaryContact);

      if (!primaryContactVerification.success) {
        return {
          success: false,
          reason: primaryContactVerification.reason,
          requiresManualReview: true
        };
      }

      // Step 2: Enterprise risk assessment
      const enterpriseRiskProfile = await this.assessEnterpriseRisk(customerData, primaryContactVerification);

      // Step 3: Determine onboarding workflow
      const onboardingWorkflow = this.determineOnboardingWorkflow(enterpriseRiskProfile, customerData);

      // Step 4: Initialize multi-stakeholder verification
      const stakeholderWorkflows = await this.initializeStakeholderVerification(stakeholders, onboardingWorkflow);

      // Step 5: Create enterprise account with verified status
      const enterpriseAccount = await this.createEnterpriseAccount({
        customerData,
        verificationData: primaryContactVerification,
        riskProfile: enterpriseRiskProfile,
        workflows: stakeholderWorkflows,
        onboardingLevel: onboardingWorkflow.level
      });

      // Step 6: Initialize integrations and setup
      await this.initializeIntegrations(enterpriseAccount, customerData.requiredIntegrations);

      return {
        success: true,
        enterpriseId: enterpriseAccount.id,
        onboardingWorkflow: stakeholderWorkflows,
        estimatedActivationTime: this.calculateActivationTime(onboardingWorkflow),
        processingTime: Date.now() - startTime
      };

    } catch (error) {
      console.error('Enterprise onboarding error:', error);

      return {
        success: false,
        error: 'Onboarding service temporarily unavailable',
        requiresManualReview: true
      };
    }
  }

  async verifyPrimaryContact(contactData) {
    try {
      // Comprehensive phone verification
      const phoneValidation = await this.phoneCheckClient.validatePhone({
        phone: contactData.phone,
        includeCarrierInfo: true,
        includeBusinessIntelligence: true,
        includeRiskScoring: true,
        includeGeolocation: true
      });

      // Business phone verification
      const businessVerification = await this.verifyBusinessPhone(phoneValidation, contactData);

      // Email validation (supplementary)
      const emailValidation = await this.validateCorporateEmail(contactData.email);

      // Identity verification scoring
      const identityScore = this.calculateIdentityScore({
        phoneValidation,
        businessVerification,
        emailValidation,
        contactData
      });

      return {
        success: identityScore >= 70,
        phoneValidation,
        businessVerification,
        emailValidation,
        identityScore,
        verificationLevel: this.determineVerificationLevel(identityScore),
        businessIntelligence: {
          isBusinessPhone: businessVerification.isBusinessPhone,
          companyMatch: businessVerification.companyMatch,
          carrierType: phoneValidation.carrier?.type,
          businessCategory: businessVerification.category
        }
      };

    } catch (error) {
      console.error('Primary contact verification error:', error);
      return {
        success: false,
        reason: 'Verification service unavailable',
        requiresManualReview: true
      };
    }
  }

  async verifyBusinessPhone(phoneValidation, contactData) {
    let businessScore = 0;
    const businessSignals = [];

    // Business phone type detection
    if (phoneValidation.type === 'BUSINESS' || phoneValidation.type === 'FIXED_LINE') {
      businessScore += 40;
      businessSignals.push('business_phone_type');
    }

    // Carrier analysis for business indicators
    if (phoneValidation.carrier) {
      const businessCarriers = [
        'at&t business', 'verizon business', 'comcast business',
        'bt business', 'orange business', 'deutsche telekom business'
      ];

      if (businessCarriers.some(carrier =>
        phoneValidation.carrier.name.toLowerCase().includes(carrier.toLowerCase()))) {
        businessScore += 30;
        businessSignals.push('verified_business_carrier');
      }

      if (phoneValidation.carrier.isBusiness) {
        businessScore += 25;
        businessSignals.push('business_carrier_plan');
      }
    }

    // Company name match detection
    if (contactData.companyName && phoneValidation.businessIntelligence) {
      const companyNameMatch = this.calculateCompanyNameMatch(
        contactData.companyName,
        phoneValidation.businessIntelligence.registeredName
      );

      if (companyNameMatch > 0.8) {
        businessScore += 35;
        businessSignals.push('company_name_match');
      }
    }

    // Geographic business indicators
    if (phoneValidation.geography && contactData.businessAddress) {
      const geographicMatch = this.verifyBusinessGeography(
        phoneValidation.geography,
        contactData.businessAddress
      );

      if (geographicMatch.isValid) {
        businessScore += 15;
        businessSignals.push('geographic_business_match');
      }
    }

    // Phone number pattern analysis
    const businessPatterns = [
      /^\+?[1-9]\d{6,14}$/, // Standard business length
      /^\d{3}-\d{3}-\d{4}$/, // North American business format
      /^\+44 \d{4} \d{6}$/ // UK business format
    ];

    if (businessPatterns.some(pattern => pattern.test(phoneValidation.number))) {
      businessScore += 10;
      businessSignals.push('business_number_format');
    }

    return {
      isBusinessPhone: businessScore >= 50,
      businessScore: Math.min(100, businessScore),
      businessSignals,
      companyMatch: phoneValidation.businessIntelligence?.registeredName || null,
      businessCategory: phoneValidation.businessIntelligence?.category || 'unknown'
    };
  }

  async assessEnterpriseRisk(customerData, verificationData) {
    let riskScore = 0;
    const riskFactors = [];
    const qualitySignals = [];

    // Verification quality assessment
    if (verificationData.identityScore >= 90) {
      riskScore -= 20;
      qualitySignals.push('high_confidence_verification');
    } else if (verificationData.identityScore >= 70) {
      riskScore -= 10;
      qualitySignals.push('standard_verification');
    } else {
      riskScore += 30;
      riskFactors.push('low_confidence_verification');
    }

    // Business phone verification impact
    if (verificationData.businessIntelligence.isBusinessPhone) {
      riskScore -= 25;
      qualitySignals.push('verified_business_phone');
    } else {
      riskScore += 40;
      riskFactors.push('non_business_phone_detected');
    }

    // Company size and type analysis
    if (customerData.employeeCount >= 1000) {
      riskScore -= 15;
      qualitySignals.push('enterprise_customer');
    } else if (customerData.employeeCount >= 100) {
      riskScore -= 10;
      qualitySignals.push('mid_market_customer');
    } else {
      riskScore += 5;
      riskFactors.push('small_business_segment');
    }

    // Industry risk assessment
    const regulatedIndustries = ['finance', 'healthcare', 'government', 'education'];
    if (regulatedIndustries.includes(customerData.industry.toLowerCase())) {
      riskScore += 20;
      riskFactors.push('regulated_industry');
    }

    // Geographic risk factors
    if (verificationData.phoneValidation.geography) {
      const highRiskCountries = ['XX', 'YY']; // Configurable based on business requirements
      if (highRiskCountries.includes(verificationData.phoneValidation.geography.countryCode)) {
        riskScore += 35;
        riskFactors.push('high_risk_geography');
      }
    }

    // Integration complexity assessment
    if (customerData.requiredIntegrations.length > 5) {
      riskScore += 15;
      riskFactors.push('complex_integration_requirements');
    }

    return {
      totalScore: Math.max(0, Math.min(100, riskScore)),
      riskFactors,
      qualitySignals,
      verificationConfidence: verificationData.identityScore,
      businessLegitimacy: verificationData.businessIntelligence.businessScore,
      recommendedOnboardingLevel: this.determineOnboardingLevel(riskScore)
    };
  }

  determineOnboardingWorkflow(riskProfile, customerData) {
    if (riskProfile.totalScore >= 70) {
      return {
        level: 'ENHANCED_DILIGENCE',
        requires: ['phone_verification', 'document_verification', 'stakeholder_approval', 'manual_review'],
        estimatedActivationTime: '5-7 business days',
        supportLevel: 'premium'
      };
    } else if (riskProfile.totalScore >= 40) {
      return {
        level: 'STANDARD_ENTERPRISE',
        requires: ['phone_verification', 'stakeholder_approval'],
        estimatedActivationTime: '2-3 business days',
        supportLevel: 'standard'
      };
    } else {
      return {
        level: 'EXPEDITED_ONBOARDING',
        requires: ['phone_verification'],
        estimatedActivationTime: '1-2 business days',
        supportLevel: 'self_service'
      };
    }
  }

  async initializeStakeholderVerification(stakeholders, workflow) {
    const stakeholderWorkflows = [];

    for (const stakeholder of stakeholders) {
      const workflowInit = {
        stakeholderId: stakeholder.id,
        stakeholderRole: stakeholder.role,
        verificationRequirements: this.getRoleBasedRequirements(stakeholder.role, workflow.level),
        verificationStatus: 'pending',
        initiatedAt: new Date().toISOString()
      };

      if (workflow.requires.includes('stakeholder_approval')) {
        // Send verification request to stakeholder
        await this.sendStakeholderVerificationRequest(stakeholder, workflowInit);
      }

      stakeholderWorkflows.push(workflowInit);
    }

    return stakeholderWorkflows;
  }

  getRoleBasedRequirements(role, onboardingLevel) {
    const baseRequirements = ['phone_verification'];

    switch (role) {
      case 'technical_contact':
        return [...baseRequirements, 'integration_verification'];
      case 'billing_contact':
        return [...baseRequirements, 'payment_method_verification'];
      case 'executive_sponsor':
        return [...baseRequirements, 'authorization_verification'];
      case 'it_administrator':
        return [...baseRequirements, 'system_access_verification'];
      default:
        return baseRequirements;
    }
  }

  async initializeIntegrations(enterpriseAccount, requiredIntegrations) {
    const integrationResults = [];

    for (const integration of requiredIntegrations) {
      try {
        const integrationInit = await this.integrationHub.initializeIntegration({
          enterpriseId: enterpriseAccount.id,
          integrationType: integration.type,
          configuration: integration.configuration,
          verificationRequired: integration.requiresVerification
        });

        integrationResults.push({
          integrationType: integration.type,
          status: 'initialized',
          integrationId: integrationInit.id,
          requiresAction: integrationInit.requiresAction
        });

      } catch (error) {
        integrationResults.push({
          integrationType: integration.type,
          status: 'failed',
          error: error.message
        });
      }
    }

    return integrationResults;
  }

  calculateActivationTime(workflow) {
    const baseTimes = {
      'EXPEDITED_ONBOARDING': 24, // hours
      'STANDARD_ENTERPRISE': 72, // hours
      'ENHANCED_DILIGENCE': 120 // hours
    };

    const complexityMultiplier = workflow.supportLevel === 'premium' ? 1.5 : 1.0;
    return Math.ceil(baseTimes[workflow.level] * complexityMultiplier);
  }
}

// Usage in enterprise signup flow
async function handleEnterpriseSignup(req, res) {
  const onboardingService = new EnterpriseOnboardingService();

  try {
    const onboardingResult = await onboardingService.initiateEnterpriseOnboarding(
      req.body.customerData,
      req.body.stakeholders
    );

    if (onboardingResult.success) {
      // Initialize customer success workflow
      await customerSuccessService.initializeEnterpriseOnboarding(
        onboardingResult.enterpriseId,
        onboardingResult.onboardingWorkflow
      );

      // Send welcome notifications
      await notificationService.sendEnterpriseWelcome(onboardingResult);

      res.status(201).json({
        success: true,
        enterpriseId: onboardingResult.enterpriseId,
        estimatedActivationTime: onboardingResult.estimatedActivationTime,
        onboardingWorkflow: onboardingResult.onboardingWorkflow
      });

    } else {
      res.status(400).json({
        success: false,
        error: onboardingResult.error,
        requiresManualReview: onboardingResult.requiresManualReview
      });
    }

  } catch (error) {
    console.error('Enterprise onboarding error:', error);
    res.status(500).json({
      success: false,
      error: 'Onboarding service temporarily unavailable'
    });
  }
}