Skip to main content
Number Lookup allows you to validate phone numbers and retrieve carrier information before sending messages. This helps you:
  • Validate numbers before adding them to your contact list
  • Identify line types (mobile, landline, VoIP) for better channel selection
  • Get carrier information for cost estimation and fraud prevention
  • Determine available channels (SMS, WhatsApp) for each number

​
API Call

Use the /v1/introspect/phone endpoint to look up phone number information.

​
Request

curl -X POST https://api.zavu.dev/v1/introspect/phone \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234"
  }'

​
Response

{
  "phoneNumber": "+14155551234",
  "validNumber": true,
  "countryCode": "US",
  "nationalFormat": "(415) 555-1234",
  "lineType": "mobile",
  "carrier": {
    "name": "Verizon Wireless",
    "type": "mobile"
  },
  "availableChannels": ["sms", "whatsapp"]
}

​
Response Fields

FieldTypeDescription
phoneNumberstringThe queried phone number in E.164 format
validNumberbooleanWhether the number is valid
countryCodestringISO 3166-1 alpha-2 country code
nationalFormatstringNumber formatted for the local country
lineTypestringType of line: mobile, landline, voip, toll_free, unknown
carrierobjectCarrier information (name and type)
availableChannelsarrayChannels available for messaging: sms, whatsapp

​
SDK Usage

​
TypeScript

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const result = await zavu.introspect.phone({
  phoneNumber: "+14155551234",
});

if (result.validNumber) {
  console.log("Valid number from:", result.countryCode);
  console.log("Line type:", result.lineType);
  console.log("Carrier:", result.carrier?.name);
  console.log("Available channels:", result.availableChannels.join(", "));
} else {
  console.log("Invalid phone number");
}

​
Python

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
)

result = zavu.introspect.phone(phone_number="+14155551234")

if result.valid_number:
    print(f"Valid number from: {result.country_code}")
    print(f"Line type: {result.line_type}")
    print(f"Carrier: {result.carrier.name if result.carrier else 'Unknown'}")
    print(f"Available channels: {', '.join(result.available_channels)}")
else:
    print("Invalid phone number")

​
Line Types

The lineType field indicates the type of phone line:
TypeDescription
mobileMobile/cellular phone
landlineFixed landline phone
voipVoice over IP service (Google Voice, Skype, etc.)
toll_freeToll-free number (1-800, etc.)
unknownUnable to determine

​
Available Channels

The availableChannels array is determined dynamically based on the line type:
Line TypeSMSWhatsAppNotes
mobileYesYesFull messaging support
voipYesNoVoIP can receive SMS but WhatsApp requires a real mobile number
toll_freeYesNoToll-free numbers support SMS only
landlineNoNoLandlines cannot receive text messages
unknownYesNoConservative: SMS is more universal
Use the availableChannels array to determine which messaging channels you can use for each number. If a channel is not in the array, messages to that channel will fail.
const result = await zavu.introspect.validatePhone({
  phoneNumber: "+14155551234",
});

// Check available channels before sending
if (result.availableChannels.includes("whatsapp")) {
  // WhatsApp is available - this is a mobile number
  await zavu.messages.send({
    to: "+14155551234",
    channel: "whatsapp",
    text: "Hello via WhatsApp!",
  });
} else if (result.availableChannels.includes("sms")) {
  // Fall back to SMS
  await zavu.messages.send({
    to: "+14155551234",
    channel: "sms",
    text: "Hello via SMS!",
  });
} else {
  // No messaging channels available (landline)
  console.error("This number cannot receive messages");
}
If availableChannels is empty, the number cannot receive any messages. This typically happens with landline numbers or invalid numbers.

​
Use Cases

​
Pre-send Validation

Validate numbers before sending messages to reduce failed deliveries: 
const result = await zavu.introspect.phone({
  phoneNumber: customerPhone,
});

if (!result.validNumber) {
  throw new Error("Invalid phone number provided");
}

// Safe to send message
await zavu.messages.send({
  to: customerPhone,
  text: "Your order has shipped!",
});

​
Channel Selection

Choose the best channel based on line type: 
const result = await zavu.introspect.phone({
  phoneNumber: customerPhone,
});

// Use WhatsApp for mobile, SMS for others
const channel = result.lineType === "mobile"
  && result.availableChannels.includes("whatsapp")
    ? "whatsapp"
    : "sms";

await zavu.messages.send({
  to: customerPhone,
  channel: channel,
  text: "Hello!",
});

​
Fraud Prevention

Identify potentially fraudulent numbers by checking line type: 
const result = await zavu.introspect.phone({
  phoneNumber: userPhone,
});

// Flag VoIP numbers for additional verification
if (result.lineType === "voip") {
  console.warn("VoIP number detected - consider additional verification");
}

​
Pricing

Number lookup requests are billed separately from messaging. See our pricing page for current rates.
Lookup results are cached for 24 hours. Subsequent lookups for the same number within this period will use the cached result.

​
Error Handling

​
Invalid Phone Number Format

{
  "code": "bad_request",
  "message": "Invalid phone number format. Use E.164 format (e.g., +14155551234)"
}

​
Rate Limit Exceeded

{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}
Always include proper error handling in your integration to gracefully handle API errors.