Number Lookup

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

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

Response

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

Response Fields

SDK Usage

TypeScript

TypeScriptCopy
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.validatePhone({
  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");
}

Line Types

The lineType field indicates the type of phone line:

Available Channels

The availableChannels array is determined dynamically based on the line type:

TypeScriptCopy
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");
}

Use Cases

Pre-send Validation

Validate numbers before sending messages to reduce failed deliveries:

TypeScriptCopy
const result = await zavu.introspect.validatePhone({
  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:

TypeScriptCopy
const result = await zavu.introspect.validatePhone({
  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:

TypeScriptCopy
const result = await zavu.introspect.validatePhone({
  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.

Error Handling

Invalid Phone Number Format

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

Rate Limit Exceeded

JSONCopy
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}