Best CallRail Phone Validation API & Call Tracking Integration 2025

// CallRail API configuration
import axios from 'axios';

class CallRailClient {
  constructor(apiToken, accountId) {
    this.apiToken = apiToken;
    this.accountId = accountId;
    this.baseURL = 'https://api.callrail.com/v3';
    this.headers = {
      'Authorization': `Token token=${apiToken}`,
      'Content-Type': 'application/json'
    };
  }

  async getAccounts() {
    try {
      const response = await axios.get(`${this.baseURL}/a.json`, {
        headers: this.headers
      });
      return response.data;
    } catch (error) {
      console.error('CallRail API error:', error.response?.data || error.message);
      throw error;
    }
  }

  async getCalls(options = {}) {
    const params = new URLSearchParams({
      page: options.page || 1,
      per_page: options.per_page || 100,
      date_range: options.date_range || 'last_30_days',
      ...options.filters
    });

    const response = await axios.get(
      `${this.baseURL}/a/${this.accountId}/calls.json?${params}`,
      { headers: this.headers }
    );
    
    return response.data;
  }

  async updateCall(callId, data) {
    const response = await axios.put(
      `${this.baseURL}/a/${this.accountId}/calls/${callId}.json`,
      data,
      { headers: this.headers }
    );
    
    return response.data;
  }
}

const callRail = new CallRailClient(
  process.env.CALLRAIL_API_TOKEN,
  process.env.CALLRAIL_ACCOUNT_ID
);

// Test the connection
const accounts = await callRail.getAccounts();
console.log('Connected to CallRail accounts:', accounts.length);

// 1lookup configuration for CallRail
import { OneLookupClient } from '@1lookup/sdk';

const oneLookup = new OneLookupClient({
  apiKey: process.env.ONELOOKUP_API_KEY,
  environment: 'production',
  timeout: 3000, // Fast response for real-time call processing
  retryAttempts: 2,
  enableAnalytics: true,
  callTrackingMode: true // Optimize for call tracking scenarios
});

// Configure validation parameters for CallRail
const callRailValidationConfig = {
  includeCarrierInfo: true,
  includeLocationInfo: true,
  includeFraudScore: true,
  includeDemographics: true,
  includeLineType: true,
  enableLeadScoring: true,
  trackAttribution: true
};

// Verify service connectivity
const healthStatus = await oneLookup.health.check();
console.log('1lookup service status:', healthStatus.status);

// Real-time CallRail webhook handler
import express from 'express';
const app = express();

app.use(express.json());

// CallRail webhook endpoint
app.post('/webhooks/callrail/call-complete', async (req, res) => {
  try {
    const callData = req.body;
    console.log('Received CallRail webhook:', callData.id);

    // Validate and enrich the caller's phone number
    const enhancement = await enhanceCallData(callData);
    
    // Update CallRail with enriched data
    await updateCallRailWithEnrichment(callData.id, enhancement);
    
    // Send to analytics pipeline
    await sendToAnalytics(callData, enhancement);
    
    res.status(200).json({ status: 'processed', callId: callData.id });
    
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

async function enhanceCallData(callData) {
  const callerNumber = callData.caller_phone_number;
  
  // Get comprehensive validation and insights
  const validation = await oneLookup.phone.validateWithInsights({
    phone: callerNumber,
    ...callRailValidationConfig,
    context: {
      source: 'callrail',
      campaign: callData.campaign_name,
      keyword: callData.keyword,
      landing_page: callData.landing_page_url
    }
  });

  // Calculate lead score based on validation data
  const leadScore = calculateLeadScore({
    validation: validation,
    callData: callData
  });

  // Analyze call attribution
  const attribution = await analyzeAttribution({
    callerLocation: validation.locationInfo,
    campaignData: {
      source: callData.source,
      medium: callData.medium,
      campaign: callData.campaign_name,
      keyword: callData.keyword
    }
  });

  return {
    validation: validation,
    leadScore: leadScore,
    attribution: attribution,
    fraudRisk: validation.fraudScore || 0,
    qualityScore: calculateQualityScore(validation, callData)
  };
}

function calculateLeadScore({ validation, callData }) {
  let score = 50; // Base score

  // Location relevance (if business has geographic targeting)
  if (validation.locationInfo) {
    const targetRegions = process.env.TARGET_REGIONS?.split(',') || [];
    if (targetRegions.includes(validation.locationInfo.region)) {
      score += 20;
    }
  }

  // Carrier type preference
  if (validation.lineType === 'mobile') {
    score += 15; // Mobile users often more engaged
  }

  // Call duration bonus
  if (callData.duration && callData.duration > 120) { // 2+ minutes
    score += 25;
  }

  // Fraud risk penalty
  if (validation.fraudScore > 0.7) {
    score -= 40;
  } else if (validation.fraudScore > 0.3) {
    score -= 15;
  }

  // Repeat caller bonus
  if (callData.first_call === false) {
    score += 10;
  }

  // Keyword quality (if available)
  if (callData.keyword && callData.keyword.includes('buy|purchase|hire|quote')) {
    score += 15;
  }

  return Math.max(0, Math.min(100, score));
}

function calculateQualityScore(validation, callData) {
  let qualityScore = 0;
  
  // Phone number validation quality
  if (validation.isValid) qualityScore += 25;
  if (validation.carrierInfo?.reputation === 'high') qualityScore += 15;
  
  // Geographic relevance
  if (validation.locationInfo?.accuracy === 'high') qualityScore += 20;
  
  // Call characteristics
  if (callData.answered) qualityScore += 20;
  if (callData.duration > 60) qualityScore += 20;
  
  return Math.min(100, qualityScore);
}

async function updateCallRailWithEnrichment(callId, enhancement) {
  const updateData = {
    tags: [
      `lead_score_${Math.round(enhancement.leadScore)}`,
      `quality_${enhancement.qualityScore > 75 ? 'high' : enhancement.qualityScore > 50 ? 'medium' : 'low'}`,
      `carrier_${enhancement.validation.carrierInfo?.type || 'unknown'}`,
      enhancement.fraudRisk > 0.7 ? 'high_fraud_risk' : null
    ].filter(Boolean),
    
    note: `Validation Score: ${enhancement.validation.confidence}%\n` +
          `Lead Score: ${enhancement.leadScore}/100\n` +
          `Location: ${enhancement.validation.locationInfo?.city || 'Unknown'}, ${enhancement.validation.locationInfo?.region || 'Unknown'}\n` +
          `Carrier: ${enhancement.validation.carrierInfo?.name || 'Unknown'}\n` +
          `Quality Score: ${enhancement.qualityScore}/100`
  };

  // Add fraud warning if detected
  if (enhancement.fraudRisk > 0.7) {
    updateData.note += '\n⚠️ HIGH FRAUD RISK DETECTED';
  }

  await callRail.updateCall(callId, updateData);
}

async function sendToAnalytics(callData, enhancement) {
  // Send enriched data to your analytics system
  const analyticsPayload = {
    timestamp: new Date().toISOString(),
    call_id: callData.id,
    caller_number: callData.caller_phone_number,
    campaign: callData.campaign_name,
    source: callData.source,
    keyword: callData.keyword,
    
    // Enrichment data
    lead_score: enhancement.leadScore,
    quality_score: enhancement.qualityScore,
    fraud_risk: enhancement.fraudRisk,
    carrier_type: enhancement.validation.carrierInfo?.type,
    caller_location: enhancement.validation.locationInfo,
    attribution_data: enhancement.attribution
  };

  // Send to your analytics platform (Google Analytics, Mixpanel, etc.)
  await oneLookup.analytics.track('call_completed', analyticsPayload);
}

app.listen(3000, () => {
  console.log('CallRail webhook server running on port 3000');
});

// Batch processing for historical CallRail data
class CallRailBatchProcessor {
  constructor(callRailClient, oneLookupClient) {
    this.callRail = callRailClient;
    this.oneLookup = oneLookupClient;
    this.batchSize = 100;
    this.rateLimitDelay = 1000; // 1 second between batches
  }

  async processHistoricalCalls(dateRange = 'last_30_days') {
    console.log(`Starting batch processing for date range: ${dateRange}`);
    
    let page = 1;
    let totalProcessed = 0;
    const results = {
      processed: 0,
      enhanced: 0,
      errors: 0,
      insights: []
    };

    try {
      while (true) {
        // Get batch of calls from CallRail
        const callsResponse = await this.callRail.getCalls({
          date_range: dateRange,
          page: page,
          per_page: this.batchSize,
          answered: 'all' // Include all calls for comprehensive analysis
        });

        const calls = callsResponse.calls;
        if (!calls || calls.length === 0) {
          break; // No more calls to process
        }

        console.log(`Processing batch ${page}, ${calls.length} calls`);

        // Process calls in parallel (limited concurrency)
        const batchPromises = calls.map(call => this.processCall(call));
        const batchResults = await Promise.allSettled(batchPromises);

        // Analyze batch results
        for (let i = 0; i < batchResults.length; i++) {
          results.processed++;
          
          if (batchResults[i].status === 'fulfilled') {
            results.enhanced++;
            if (batchResults[i].value.insights) {
              results.insights.push(batchResults[i].value.insights);
            }
          } else {
            results.errors++;
            console.error(`Error processing call ${calls[i].id}:`, batchResults[i].reason);
          }
        }

        // Rate limiting
        await new Promise(resolve => setTimeout(resolve, this.rateLimitDelay));
        page++;
      }

      // Generate summary insights
      const summaryInsights = this.generateSummaryInsights(results.insights);
      
      console.log(`Batch processing complete:
        - Total processed: ${results.processed}
        - Successfully enhanced: ${results.enhanced}
        - Errors: ${results.errors}
        - Success rate: ${((results.enhanced / results.processed) * 100).toFixed(2)}%`);

      return {
        ...results,
        summaryInsights: summaryInsights
      };

    } catch (error) {
      console.error('Batch processing error:', error);
      throw error;
    }
  }

  async processCall(callData) {
    try {
      // Skip if no caller number
      if (!callData.caller_phone_number) {
        return { status: 'skipped', reason: 'no_phone_number' };
      }

      // Validate and enhance
      const validation = await this.oneLookup.phone.validateWithInsights({
        phone: callData.caller_phone_number,
        includeCarrierInfo: true,
        includeLocationInfo: true,
        includeFraudScore: true,
        includeDemographics: true
      });

      // Calculate metrics
      const leadScore = calculateLeadScore({ validation, callData });
      const qualityScore = calculateQualityScore(validation, callData);

      // Update CallRail with enhancement
      await this.updateCallWithEnrichment(callData.id, validation, leadScore, qualityScore);

      // Extract insights for summary
      const insights = this.extractCallInsights(callData, validation, leadScore, qualityScore);

      return {
        status: 'success',
        callId: callData.id,
        leadScore: leadScore,
        qualityScore: qualityScore,
        insights: insights
      };

    } catch (error) {
      return {
        status: 'error',
        callId: callData.id,
        error: error.message
      };
    }
  }

  async updateCallWithEnrichment(callId, validation, leadScore, qualityScore) {
    const tags = [
      `enhanced_${new Date().toISOString().split('T')[0]}`,
      `lead_score_${Math.round(leadScore)}`,
      `quality_${qualityScore > 75 ? 'high' : qualityScore > 50 ? 'medium' : 'low'}`
    ];

    const note = `AUTO-ENHANCED DATA:\n` +
                `Lead Score: ${leadScore}/100\n` +
                `Quality Score: ${qualityScore}/100\n` +
                `Carrier: ${validation.carrierInfo?.name || 'Unknown'}\n` +
                `Location: ${validation.locationInfo?.city || 'Unknown'}, ${validation.locationInfo?.region || 'Unknown'}\n` +
                `Validation Confidence: ${validation.confidence}%`;

    await this.callRail.updateCall(callId, { tags, note });
  }

  extractCallInsights(callData, validation, leadScore, qualityScore) {
    return {
      call_id: callData.id,
      date: callData.start_time,
      campaign: callData.campaign_name,
      source: callData.source,
      keyword: callData.keyword,
      duration: callData.duration,
      answered: callData.answered,
      
      // Enhanced data
      lead_score: leadScore,
      quality_score: qualityScore,
      carrier: validation.carrierInfo?.name,
      location: {
        city: validation.locationInfo?.city,
        state: validation.locationInfo?.region,
        country: validation.locationInfo?.country
      },
      fraud_risk: validation.fraudScore,
      line_type: validation.lineType
    };
  }

  generateSummaryInsights(insights) {
    if (insights.length === 0) return null;

    // Calculate aggregated metrics
    const avgLeadScore = insights.reduce((sum, i) => sum + i.lead_score, 0) / insights.length;
    const avgQualityScore = insights.reduce((sum, i) => sum + i.quality_score, 0) / insights.length;
    const avgDuration = insights.filter(i => i.duration).reduce((sum, i) => sum + i.duration, 0) / insights.filter(i => i.duration).length;

    // Top performing campaigns
    const campaignPerformance = {};
    insights.forEach(insight => {
      if (insight.campaign) {
        if (!campaignPerformance[insight.campaign]) {
          campaignPerformance[insight.campaign] = { calls: 0, totalLeadScore: 0, totalQuality: 0 };
        }
        campaignPerformance[insight.campaign].calls++;
        campaignPerformance[insight.campaign].totalLeadScore += insight.lead_score;
        campaignPerformance[insight.campaign].totalQuality += insight.quality_score;
      }
    });

    const topCampaigns = Object.entries(campaignPerformance)
      .map(([campaign, data]) => ({
        campaign,
        calls: data.calls,
        avgLeadScore: data.totalLeadScore / data.calls,
        avgQualityScore: data.totalQuality / data.calls
      }))
      .sort((a, b) => b.avgLeadScore - a.avgLeadScore)
      .slice(0, 10);

    // Geographic insights
    const locationInsights = {};
    insights.forEach(insight => {
      const state = insight.location?.state;
      if (state) {
        if (!locationInsights[state]) {
          locationInsights[state] = { calls: 0, totalLeadScore: 0 };
        }
        locationInsights[state].calls++;
        locationInsights[state].totalLeadScore += insight.lead_score;
      }
    });

    return {
      totalCalls: insights.length,
      avgLeadScore: Math.round(avgLeadScore),
      avgQualityScore: Math.round(avgQualityScore),
      avgDuration: Math.round(avgDuration),
      topCampaigns: topCampaigns,
      topStates: Object.entries(locationInsights)
        .map(([state, data]) => ({
          state,
          calls: data.calls,
          avgLeadScore: Math.round(data.totalLeadScore / data.calls)
        }))
        .sort((a, b) => b.avgLeadScore - a.avgLeadScore)
        .slice(0, 10),
      highQualityCalls: insights.filter(i => i.quality_score > 75).length,
      fraudulentCalls: insights.filter(i => i.fraud_risk > 0.7).length
    };
  }
}

// Usage
const processor = new CallRailBatchProcessor(callRail, oneLookup);
const results = await processor.processHistoricalCalls('last_30_days');
console.log('Processing results:', results.summaryInsights);