Phone Numbers

When to Use

Use this skill when building code to search for, purchase, or manage phone numbers. Covers available number search, purchasing, regulatory requirements, and sender assignment.

Search Available Numbers

const result = await zavu.phoneNumbers.available.list({
  countryCode: "US",
  type: "local",
  contains: "555",
  limit: 10,
});

for (const number of result.items) {
  console.log(number.phoneNumber);       // +15551234567
  console.log(number.friendlyName);      // (555) 123-4567
  console.log(number.locality);          // San Francisco
  console.log(number.capabilities);      // { sms: true, voice: true, mms: true }
  console.log(number.pricing.monthlyPrice); // 1.25
  console.log(number.pricing.isFreeEligible); // true (first US number is free)
}

Python:

result = zavu.phone_numbers.available.list(
    country_code="US",
    type="local",
    contains="555",
    limit=10,
)
for number in result.items:
    print(number.phone_number, number.pricing.monthly_price)

Purchase Phone Number

const result = await zavu.phoneNumbers.create({
  phoneNumber: "+15551234567",
  name: "Primary Line",
});
console.log(result.phoneNumber.id);     // pn_abc123
console.log(result.phoneNumber.status); // "active"

First US number is free for each team.

Phone Number Types

Manage Phone Numbers

// List owned numbers
const numbers = await zavu.phoneNumbers.list({ status: "active" });
for (const pn of numbers.items) {
  console.log(pn.id, pn.phoneNumber, pn.status);
}

// Get details
const pn = await zavu.phoneNumbers.get({ phoneNumberId: "pn_abc123" });

// Rename
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  name: "Support Line",
});

// Assign to sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: "snd_abc123",
});

// Unassign from sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: null,
});

// Release number (must not be assigned to a sender)
await zavu.phoneNumbers.delete({ phoneNumberId: "pn_abc123" });

Regulatory Requirements

Some countries require additional documentation before phone numbers can be activated:

// Check requirements for a country
const requirements = await zavu.phoneNumbers.requirements.list({
  countryCode: "DE",
  type: "local",
});

for (const req of requirements.items) {
  console.log(req.countryCode, req.phoneNumberType, req.action);
  for (const rt of req.requirementTypes) {
    console.log(`  ${rt.name}: ${rt.type} - ${rt.description}`);
  }
}

Requirement Types

Create Regulatory Address

const address = await zavu.addresses.create({
  firstName: "John",
  lastName: "Doe",
  streetAddress: "123 Main St",
  locality: "Berlin",
  postalCode: "10115",
  countryCode: "DE",
});
console.log(address.address.status); // "pending" -> "verified"

Upload Regulatory Document

// 1. Get upload URL
const upload = await zavu.documents.uploadUrl();

// 2. Upload file to the presigned URL (use fetch/axios)
await fetch(upload.uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: { "Content-Type": "image/jpeg" },
});

// 3. Create document record
const doc = await zavu.documents.create({
  name: "Passport Scan",
  documentType: "passport",
  storageId: "kg2abc123...",
  mimeType: "image/jpeg",
  fileSize: 102400,
});
console.log(doc.document.status); // "pending" -> "verified"

Document Types

10DLC (US A2P Messaging)

For US application-to-person messaging at scale, you may need 10DLC registration:

1. Brand Registration - Register your business identity
2. Campaign Registration - Register your messaging use case
3. Number Assignment - Assign registered numbers to campaigns

10DLC registration is managed through the Zavu dashboard. Contact support for high-volume US messaging requirements.

Constraints

• First US phone number is free per team
• Phone number name: max 100 characters
• Phone numbers must be unassigned from senders before release
• Regulatory addresses and documents go through verification (pending -> verified/rejected)
• Country code: 2-letter ISO format (e.g., US, DE, BR)
• Search results: max 50 per request
• Some countries require verified address + document before number activation