Phone Validation for AI Voice Agents: Carrier Lookup, Fraud Screening, and Call Routing

# Pre-call validation: Check the number before dialing
curl -X GET \
  "https://api.phone-check.app/v1/phone/validate?phone=+14155552671" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "valid": true,
  "phone": "+14155552671",
  "line_type": "mobile",
  "carrier": "T-Mobile USA",
  "country": "US",
  "region": "California",
  "timezone": "America/Los_Angeles",
  "ported": false,
  "risk_score": "low",
  "connectivity": "active"
}

// Pre-call validation middleware for AI voice agents
interface ValidationResult {
  valid: boolean;
  lineType: string;
  carrier: string;
  country: string;
  timezone: string;
  riskScore: string;
  connectivity: string;
}

async function validatePhone(phone: string): Promise<ValidationResult> {
  const response = await fetch(
    "https://api.phone-check.app/v1/phone/validate?" +
    new URLSearchParams({ phone }),
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );
  const data = await response.json();
  return {
    valid: data.valid,
    lineType: data.line_type,
    carrier: data.carrier,
    country: data.country,
    timezone: data.timezone,
    riskScore: data.risk_score,
    connectivity: data.connectivity,
  };
}

// Call routing decision based on validation
type CallDecision = "connect" | "sms_fallback" | "block" | "skip";

function routeCall(result: ValidationResult): CallDecision {
  if (!result.valid || result.connectivity === "disconnected") {
    return "skip";
  }
  if (result.lineType === "voip" && result.riskScore === "high") {
    return "block";
  }
  if (result.lineType === "landline") {
    return "sms_fallback";
  }
  return "connect";
}

// Use in your voice agent webhook handler
async function handleOutboundCall(phone: string) {
  const validation = await validatePhone(phone);
  const decision = routeCall(validation);

  switch (decision) {
    case "connect":
      // Initiate voice agent call via Vapi/Retell/Twilio
      return { action: "call", data: validation };
    case "sms_fallback":
      // Queue SMS instead of voice call
      return { action: "sms", data: validation };
    case "block":
      // Log fraud attempt, do not contact
      return { action: "block", reason: "high_risk_voip" };
    case "skip":
      // Mark as unreachable, skip entirely
      return { action: "skip", reason: validation.connectivity };
  }
}

// Inbound call screening for voice agents
async function screenInboundCall(callerPhone: string) {
  const result = await validatePhone(callerPhone);

  // Flag high-risk callers
  if (result.riskScore === "high") {
    return {
      allow: false,
      reason: "high_risk_caller",
      fallback: "voicemail",
    };
  }

  // Block known disposable/burner numbers
  if (result.lineType === "voip" && result.riskScore === "medium") {
    return {
      allow: false,
      reason: "voip_caller",
      fallback: "ivR_menu",
    };
  }

  // Detect premium-rate number fraud attempts
  if (result.lineType === "premium_rate") {
    return {
      allow: false,
      reason: "premium_rate_detected",
      fallback: "block",
    };
  }

  // Enrich legitimate callers with carrier/timezone
  return {
    allow: true,
    callerData: {
      carrier: result.carrier,
      country: result.country,
      timezone: result.timezone,
      lineType: result.lineType,
    },
  };
}

// Timezone-aware call scheduling for voice agents
function shouldCallNow(
  timezone: string,
  businessStart: number = 9,
  businessEnd: number = 17
): boolean {
  const now = new Date();

  // Get the local hour in the lead's timezone
  const localTime = new Date(
    now.toLocaleString("en-US", { timeZone: timezone })
  );
  const localHour = localTime.getHours();

  return localHour >= businessStart && localHour < businessEnd;
}

// Batch scheduling: Sort call queue by timezone
function scheduleCallQueue(contacts: Array<{
  phone: string;
  timezone: string;
}>) {
  const nowCallable = contacts.filter(c =>
    shouldCallNow(c.timezone)
  );
  const laterCallable = contacts.filter(c =>
    !shouldCallNow(c.timezone)
  );

  return {
    callNow: nowCallable,
    callLater: laterCallable,
  };
}

// MCP tool definition for voice agent phone validation
{
  "name": "validate_phone_for_call",
  "description": "Validate a phone number before a voice agent "
    + "initiates a call. Returns validity, line type, carrier, "
    + "timezone, risk score, and connectivity status.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "phone": {
        "type": "string",
        "description": "Phone number in E.164 or local format"
      }
    },
    "required": ["phone"]
  }
}

// The voice agent uses this tool in its decision loop:
// 1. Agent receives a list of numbers to call
// 2. For each number, agent calls validate_phone_for_call
// 3. Based on response, agent decides: call, SMS, skip, or block
// 4. Agent initiates calls only for validated mobile numbers