Build Phone Validation into Your App: Real-Time & Bulk Verification Guide

// POST /api/v1/phone-details
// Validate a phone number during signup

async function validateSignupPhone(phone: string) {
  const response = await fetch(
    "https://api.phone-check.app/v1/phone-details",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
      },
      body: JSON.stringify({
        phone_number: phone,
        include_carrier: true,
        include_location: true,
        include_risk: true
      })
    }
  );

  const data = await response.json();

  // Block VoIP and landline numbers from SMS signup
  if (data.line_type === "voip") {
    return { valid: false, reason: "VoIP numbers not accepted" };
  }
  if (data.line_type === "landline") {
    return { valid: false, reason: "Please provide a mobile number" };
  }
  if (!data.valid) {
    return { valid: false, reason: "Invalid phone number" };
  }
  if (data.risk_score > 75) {
    return { valid: false, reason: "High-risk number detected" };
  }

  return {
    valid: true,
    carrier: data.carrier.name,
    country: data.location.country,
    lineType: data.line_type,
    timezone: data.location.timezone
  };
}

// Server-side validation for contact/lead forms
async function handleFormSubmission(formData: FormData) {
  const phone = formData.get("phone") as string;

  const validation = await validateSignupPhone(phone);

  if (!validation.valid) {
    // Return error without revealing why
    return {
      success: false,
      message: "Please provide a valid mobile number"
    };
  }

  // Store enriched data with the lead
  await db.leads.create({
    phone: phone,
    carrier: validation.carrier,
    country: validation.country,
    lineType: validation.lineType,
    timezone: validation.timezone,
    // ... other form fields
  });

  return { success: true };
}

// POST /api/v1/bulk-validate
// Process multiple phone numbers in a single request

async function bulkValidateNumbers(phoneNumbers: string[]) {
  const response = await fetch(
    "https://api.phone-check.app/v1/bulk-validate",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
      },
      body: JSON.stringify({
        phone_numbers: phoneNumbers,
        include_carrier: true,
        include_location: true,
        include_line_type: true,
        include_risk: true
      })
    }
  );

  const result = await response.json();
  // result.results contains enriched data for each number

  // Segment numbers by line type
  const mobile = result.results.filter(
    (r) => r.line_type === "mobile" && r.valid
  );
  const landline = result.results.filter(
    (r) => r.line_type === "landline"
  );
  const voip = result.results.filter(
    (r) => r.line_type === "voip"
  );
  const invalid = result.results.filter(
    (r) => !r.valid
  );

  console.log(`Mobile: ${mobile.length}`);
  console.log(`Landline: ${landline.length}`);
  console.log(`VoIP: ${voip.length}`);
  console.log(`Invalid: ${invalid.length}`);

  return { mobile, landline, voip, invalid };
}

// Webhook endpoint for bulk validation completion
// POST /api/webhooks/validation-complete

export async function handleValidationWebhook(
  req: Request
) {
  const payload = await req.json();

  if (payload.event === "bulk_validation_complete") {
    const { job_id, results, summary } = payload;

    // Update CRM records with enriched phone data
    for (const result of results) {
      await crm.updateContact(result.reference_id, {
        phoneValid: result.valid,
        lineType: result.line_type,
        carrier: result.carrier?.name,
        timezone: result.location?.timezone,
        riskScore: result.risk_score,
      });
    }

    // Log summary metrics
    console.log(`Job ${job_id} complete:`, summary);
    // Output: { total: 50000, valid: 42300,
    //          mobile: 38100, landline: 4200, invalid: 7700 }
  }
}

// Robust error handling for phone validation
async function safeValidatePhone(phone: string) {
  try {
    const response = await fetch(
      "https://api.phone-check.app/v1/phone-details",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${process.env.API_KEY}`
        },
        body: JSON.stringify({
          phone_number: phone,
          include_carrier: true,
          include_location: true,
        }),
        signal: AbortSignal.timeout(5000) // 5s timeout
      }
    );

    if (!response.ok) {
      // Handle rate limiting with retry
      if (response.status === 429) {
        const retryAfter = response.headers.get("Retry-After");
        console.warn(`Rate limited. Retry after ${retryAfter}s`);
        return { valid: false, reason: "temporarily_unavailable" };
      }

      throw new Error(`API error: ${response.status}`);
    }

    const data = await response.json();

    // Handle partial results gracefully
    return {
      valid: data.valid ?? false,
      lineType: data.line_type ?? "unknown",
      carrier: data.carrier?.name ?? null,
      timezone: data.location?.timezone ?? null,
      riskScore: data.risk_score ?? 0,
    };

  } catch (error) {
    // Fail open: don't block users if API is down
    console.error("Validation failed:", error);
    return {
      valid: "unknown",
      reason: "validation_service_unavailable"
    };
  }
}