Phone Numbers

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 (paid plans include one US number, once per account)
}

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)

Go:

result, err := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchParams{
    CountryCode: zavudev.String("US"),
    Type:        zavudev.String("local"),
    Contains:    zavudev.String("555"),
    Limit:       zavudev.Int(10),
})
for _, number := range result.Items {
    fmt.Println(number.PhoneNumber, number.Pricing.MonthlyPrice)
}

Ruby:

result = client.phone_numbers.search_available(country_code: "US", type: "local", contains: "555", limit: 10)
result.items.each { |number| puts "#{number.phone_number} #{number.pricing.monthly_price}" }

PHP:

$result = $client->phoneNumbers->searchAvailable([
    'countryCode' => 'US', 'type' => 'local', 'contains' => '555', 'limit' => 10,
]);
foreach ($result->items as $number) {
    echo $number->phoneNumber . ' ' . $number->pricing->monthlyPrice . "\n";
}

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"

Buying numbers requires a paid plan. The Free plan cannot purchase phone numbers (the API returns 402 with code paid_plan_required). Paid plans include the first US number at no charge.

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

Registration charges The Campaign Registry's own fees from your balance, passed through at cost, as two separate charges:

One-time fees are charged at submission and refunded if the carrier rejects the registration. The monthly campaign fee starts once the campaign is approved.

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

Constraints

• Phone number purchase requires a paid plan (402 paid_plan_required on Free); paid plans include the first US number
• 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