Regulatory Requirements

Some countries require additional documentation before phone numbers can be activated for messaging. This includes identity verification documents, proof of address, or business registration papers.

Overview

When purchasing phone numbers in countries with regulatory requirements, you’ll need to:

Check requirements for the specific country and number type
Create addresses if address verification is required
Upload documents if identity verification is required
Submit requirements along with your purchase request

Phone numbers in the US and Canada typically don’t require additional documentation. Requirements are most common in European, Latin American, and Asian countries.

Checking Requirements

Before purchasing, check what requirements apply:

const requirements = await zavu.phoneNumbers.requirements({
  countryCode: "DE",
  type: "local",
});

for (const req of requirements.items) {
  console.log("Requirement:", req.id);
  for (const type of req.requirementTypes) {
    console.log("  -", type.name, `(${type.type})`);
    console.log("   ", type.description);
  }
}

requirements = zavu.phone_numbers.requirements(
    country_code="DE",
    type="local"
)

for req in requirements.items:
    print("Requirement:", req.id)
    for type in req.requirement_types:
        print(f"  - {type.name} ({type.type})")
        print(f"    {type.description}")

requirements = client.phone_numbers.requirements(
  country_code: "DE",
  type: "local"
)

requirements.items.each do |req|
  puts "Requirement: #{req.id}"
  req.requirement_types.each do |type|
    puts "  - #{type.name} (#{type.type})"
    puts "    #{type.description}"
  end
end

requirements, _ := client.PhoneNumbers.Requirements(context.TODO(), zavudev.PhoneNumberRequirementsParams{
	CountryCode: zavudev.String("DE"),
	Type:        zavudev.String("local"),
})

for _, req := range requirements.Items {
	fmt.Println("Requirement:", req.ID)
	for _, t := range req.RequirementTypes {
		fmt.Printf("  - %s (%s)\n", t.Name, t.Type)
		fmt.Printf("    %s\n", t.Description)
	}
}

$requirements = $client->phoneNumbers->requirements([
    'countryCode' => 'DE',
    'type' => 'local',
]);

foreach ($requirements->items as $req) {
    echo "Requirement: {$req->id}\n";
    foreach ($req->requirementTypes as $type) {
        echo "  - {$type->name} ({$type->type})\n";
        echo "    {$type->description}\n";
    }
}

curl "https://api.zavu.dev/v1/phone-numbers/requirements?countryCode=DE&type=local" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Requirement Types

Type	Description
`address`	A verified physical address is required
`document`	Identity or business document verification is required
`textual`	Text information (e.g., business name) is required

Response

{
  "items": [
    {
      "id": "req_12345",
      "countryCode": "DE",
      "phoneNumberType": "local",
      "action": "ordering",
      "requirementTypes": [
        {
          "id": "rt_address_de",
          "name": "German Address",
          "description": "A verified address within Germany",
          "type": "address",
          "acceptanceCriteria": {
            "address_countries": ["DE"]
          }
        },
        {
          "id": "rt_id_document",
          "name": "Identity Document",
          "description": "Government-issued ID (passport, national ID)",
          "type": "document",
          "acceptanceCriteria": {
            "document_types": ["passport", "national_id", "drivers_license"]
          }
        }
      ]
    }
  ]
}

Creating Addresses

If an address requirement exists, create an address first:

const address = await zavu.addresses.create({
  firstName: "John",
  lastName: "Doe",
  streetAddress: "Unter den Linden 77",
  locality: "Berlin",
  administrativeArea: "Berlin",
  postalCode: "10117",
  countryCode: "DE",
});

console.log("Address ID:", address.id);
console.log("Status:", address.status);

address = zavu.addresses.create(
    first_name="John",
    last_name="Doe",
    street_address="Unter den Linden 77",
    locality="Berlin",
    administrative_area="Berlin",
    postal_code="10117",
    country_code="DE"
)

print("Address ID:", address.id)
print("Status:", address.status)

address = client.addresses.create(
  first_name: "John",
  last_name: "Doe",
  street_address: "Unter den Linden 77",
  locality: "Berlin",
  administrative_area: "Berlin",
  postal_code: "10117",
  country_code: "DE"
)

puts "Address ID: #{address.id}"
puts "Status: #{address.status}"

address, _ := client.Addresses.New(context.TODO(), zavudev.AddressCreateParams{
	FirstName:          zavudev.String("John"),
	LastName:           zavudev.String("Doe"),
	StreetAddress:      zavudev.String("Unter den Linden 77"),
	Locality:           zavudev.String("Berlin"),
	AdministrativeArea: zavudev.String("Berlin"),
	PostalCode:         zavudev.String("10117"),
	CountryCode:        zavudev.String("DE"),
})

fmt.Println("Address ID:", address.ID)
fmt.Println("Status:", address.Status)

$address = $client->addresses->create([
    'firstName' => 'John',
    'lastName' => 'Doe',
    'streetAddress' => 'Unter den Linden 77',
    'locality' => 'Berlin',
    'administrativeArea' => 'Berlin',
    'postalCode' => '10117',
    'countryCode' => 'DE',
]);

echo "Address ID: {$address->id}\n";
echo "Status: {$address->status}\n";

curl -X POST https://api.zavu.dev/v1/addresses \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "streetAddress": "Unter den Linden 77",
    "locality": "Berlin",
    "administrativeArea": "Berlin",
    "postalCode": "10117",
    "countryCode": "DE"
  }'

Address Fields

Field	Type	Required	Description
`firstName`	string	No	First name of the individual
`lastName`	string	No	Last name of the individual
`businessName`	string	No	Business name (for business addresses)
`streetAddress`	string	Yes	Street address line 1
`extendedAddress`	string	No	Street address line 2 (apartment, suite, etc.)
`locality`	string	Yes	City or town
`administrativeArea`	string	No	State, province, or region
`postalCode`	string	Yes	Postal or ZIP code
`countryCode`	string	Yes	Two-letter ISO country code

Address Statuses

Status	Description
`pending`	Address submitted and awaiting verification
`verified`	Address has been verified and can be used
`rejected`	Address verification failed

Address verification typically completes within a few minutes but may take up to 24 hours in some cases.

Uploading Documents

If a document requirement exists, upload the required document:

// Step 1: Get upload URL
const { uploadUrl } = await zavu.regulatoryDocuments.uploadURL();

// Step 2: Upload the file to Convex storage
const uploadResponse = await fetch(uploadUrl, {
  method: "POST",
  headers: { "Content-Type": "image/jpeg" },
  body: fileBuffer,
});
const { storageId } = await uploadResponse.json();

// Step 3: Create document record with the storageId
const document = await zavu.regulatoryDocuments.create({
  name: "John Doe Passport",
  documentType: "passport",
  storageId: storageId,
  mimeType: "image/jpeg",
  fileSize: fileBuffer.byteLength,
});

console.log("Document ID:", document.id);
console.log("Status:", document.status);

# Step 1: Get upload URL
upload_result = zavu.regulatory_documents.upload_url()

# Step 2: Upload the file to Convex storage
import requests
with open("passport.jpg", "rb") as f:
    file_data = f.read()
    response = requests.post(
        upload_result.upload_url,
        headers={"Content-Type": "image/jpeg"},
        data=file_data
    )
    storage_id = response.json()["storageId"]

# Step 3: Create document record with the storageId
document = zavu.regulatory_documents.create(
    name="John Doe Passport",
    document_type="passport",
    storage_id=storage_id,
    mime_type="image/jpeg",
    file_size=len(file_data)
)

print("Document ID:", document.id)
print("Status:", document.status)

# Step 1: Get upload URL
upload_result = client.regulatory_documents.upload_url

# Step 2: Upload the file to Convex storage
require "net/http"
file_data = File.binread("passport.jpg")
uri = URI(upload_result.upload_url)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "image/jpeg"
request.body = file_data
response = http.request(request)
storage_id = JSON.parse(response.body)["storageId"]

# Step 3: Create document record with the storageId
document = client.regulatory_documents.create(
  name: "John Doe Passport",
  document_type: "passport",
  storage_id: storage_id,
  mime_type: "image/jpeg",
  file_size: file_data.bytesize
)

puts "Document ID: #{document.id}"
puts "Status: #{document.status}"

// Step 1: Get upload URL
uploadResult, _ := client.RegulatoryDocuments.UploadURL(context.TODO())

// Step 2: Upload the file to Convex storage
fileData, _ := os.ReadFile("passport.jpg")
req, _ := http.NewRequest("POST", uploadResult.UploadURL, bytes.NewReader(fileData))
req.Header.Set("Content-Type", "image/jpeg")
resp, _ := http.DefaultClient.Do(req)
var uploadResp struct{ StorageID string `json:"storageId"` }
json.NewDecoder(resp.Body).Decode(&uploadResp)

// Step 3: Create document record with the storageId
document, _ := client.RegulatoryDocuments.New(context.TODO(), zavudev.RegulatoryDocumentCreateParams{
	Name:         zavudev.String("John Doe Passport"),
	DocumentType: zavudev.String("passport"),
	StorageID:    zavudev.String(uploadResp.StorageID),
	MimeType:     zavudev.String("image/jpeg"),
	FileSize:     zavudev.Int(len(fileData)),
})

fmt.Println("Document ID:", document.ID)
fmt.Println("Status:", document.Status)

// Step 1: Get upload URL
$uploadResult = $client->regulatoryDocuments->uploadURL();

// Step 2: Upload the file to Convex storage
$fileData = file_get_contents('passport.jpg');
$ch = curl_init($uploadResult->uploadUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fileData);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: image/jpeg']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));
curl_close($ch);
$storageId = $response->storageId;

// Step 3: Create document record with the storageId
$document = $client->regulatoryDocuments->create([
    'name' => 'John Doe Passport',
    'documentType' => 'passport',
    'storageId' => $storageId,
    'mimeType' => 'image/jpeg',
    'fileSize' => strlen($fileData),
]);

echo "Document ID: {$document->id}\n";
echo "Status: {$document->status}\n";

# Step 1: Get upload URL
curl -X POST https://api.zavu.dev/v1/documents/upload-url \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

# Step 2: Upload file to the returned URL (returns storageId)
STORAGE_ID=$(curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @passport.jpg | jq -r '.storageId')

# Step 3: Create document record
curl -X POST https://api.zavu.dev/v1/documents \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"John Doe Passport\",
    \"documentType\": \"passport\",
    \"storageId\": \"$STORAGE_ID\",
    \"mimeType\": \"image/jpeg\",
    \"fileSize\": 102400
  }"

Supported Document Types

Type	Description
`passport`	Government-issued passport
`national_id`	National identity card
`drivers_license`	Driver’s license
`utility_bill`	Utility bill (for proof of address)
`tax_id`	Tax identification document
`business_registration`	Business registration certificate
`proof_of_address`	Bank statement or official letter
`other`	Other document type

File Requirements

Formats: JPEG, PNG, or PDF
Max size: 10MB
Quality: Clear, readable scan or photo
Validity: Document must not be expired

Document Statuses

Status	Description
`pending`	Document uploaded and awaiting review
`uploaded`	Document received and processing
`verified`	Document verified and accepted
`rejected`	Document rejected (check `rejectionReason`)

Purchasing with Requirements

Once you have your addresses and documents ready, include them in your purchase:

const phoneNumber = await zavu.phoneNumbers.purchase({
  phoneNumber: "+4930123456789",
  name: "Germany Line",
  regulatoryRequirements: [
    {
      requirementType: "rt_address_de",
      fieldValue: "addr_abc123",
    },
    {
      requirementType: "rt_id_document",
      fieldValue: "doc_xyz789",
    },
  ],
});

phone_number = zavu.phone_numbers.purchase(
    phone_number="+4930123456789",
    name="Germany Line",
    regulatory_requirements=[
        {
            "requirement_type": "rt_address_de",
            "field_value": "addr_abc123"
        },
        {
            "requirement_type": "rt_id_document",
            "field_value": "doc_xyz789"
        }
    ]
)

phone_number = client.phone_numbers.purchase(
  phone_number: "+4930123456789",
  name: "Germany Line",
  regulatory_requirements: [
    { requirement_type: "rt_address_de", field_value: "addr_abc123" },
    { requirement_type: "rt_id_document", field_value: "doc_xyz789" }
  ]
)

phoneNumber, _ := client.PhoneNumbers.Purchase(context.TODO(), zavudev.PhoneNumberPurchaseParams{
	PhoneNumber: zavudev.String("+4930123456789"),
	Name:        zavudev.String("Germany Line"),
	RegulatoryRequirements: []zavudev.RegulatoryRequirement{
		{RequirementType: "rt_address_de", FieldValue: "addr_abc123"},
		{RequirementType: "rt_id_document", FieldValue: "doc_xyz789"},
	},
})

$phoneNumber = $client->phoneNumbers->purchase([
    'phoneNumber' => '+4930123456789',
    'name' => 'Germany Line',
    'regulatoryRequirements' => [
        ['requirementType' => 'rt_address_de', 'fieldValue' => 'addr_abc123'],
        ['requirementType' => 'rt_id_document', 'fieldValue' => 'doc_xyz789'],
    ],
]);

curl -X POST https://api.zavu.dev/v1/phone-numbers \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+4930123456789",
    "name": "Germany Line",
    "regulatoryRequirements": [
      {
        "requirementType": "rt_address_de",
        "fieldValue": "addr_abc123"
      },
      {
        "requirementType": "rt_id_document",
        "fieldValue": "doc_xyz789"
      }
    ]
  }'

All required documents and addresses must have a verified or pending status before they can be used in a purchase request.

Managing Addresses

List Addresses

const result = await zavu.addresses.list();

for (const address of result.items) {
  console.log(address.id, address.streetAddress, address.status);
}

result = zavu.addresses.list()

for address in result.items:
    print(address.id, address.street_address, address.status)

result = client.addresses.list

result.items.each do |address|
  puts "#{address.id} #{address.street_address} #{address.status}"
end

result, _ := client.Addresses.List(context.TODO(), zavudev.AddressListParams{})

for _, address := range result.Items {
	fmt.Println(address.ID, address.StreetAddress, address.Status)
}

$result = $client->addresses->list();

foreach ($result->items as $address) {
    echo "{$address->id} {$address->streetAddress} {$address->status}\n";
}

curl "https://api.zavu.dev/v1/addresses" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Delete Address

await zavu.addresses.delete("addr_abc123");

zavu.addresses.delete("addr_abc123")

client.addresses.delete("addr_abc123")

client.Addresses.Delete(context.TODO(), "addr_abc123")

$client->addresses->delete('addr_abc123');

curl -X DELETE https://api.zavu.dev/v1/addresses/addr_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

You cannot delete an address that is currently being used for an active phone number.

Managing Documents

List Documents

const result = await zavu.regulatoryDocuments.list();

for (const doc of result.items) {
  console.log(doc.id, doc.name, doc.status);
}

result = zavu.regulatory_documents.list()

for doc in result.items:
    print(doc.id, doc.name, doc.status)

result = client.regulatory_documents.list

result.items.each do |doc|
  puts "#{doc.id} #{doc.name} #{doc.status}"
end

result, _ := client.RegulatoryDocuments.List(context.TODO(), zavudev.RegulatoryDocumentListParams{})

for _, doc := range result.Items {
	fmt.Println(doc.ID, doc.Name, doc.Status)
}

$result = $client->regulatoryDocuments->list();

foreach ($result->items as $doc) {
    echo "{$doc->id} {$doc->name} {$doc->status}\n";
}

curl "https://api.zavu.dev/v1/documents" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Delete Document

await zavu.regulatoryDocuments.delete("doc_xyz789");

zavu.regulatory_documents.delete("doc_xyz789")

client.regulatory_documents.delete("doc_xyz789")

client.RegulatoryDocuments.Delete(context.TODO(), "doc_xyz789")

$client->regulatoryDocuments->delete('doc_xyz789');

curl -X DELETE https://api.zavu.dev/v1/documents/doc_xyz789 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Country-Specific Requirements

Here are common requirements for popular countries:

Germany (DE)

Local address within Germany
Identity document (passport or national ID)
Business registration (for business numbers)

United Kingdom (GB)

UK address
Proof of identity
Proof of address (utility bill or bank statement)

France (FR)

French address
Identity document
Proof of address

Mexico (MX)

Mexican address
RFC (tax ID) for businesses
Identity document

Brazil (BR)

Brazilian address
CPF (individual) or CNPJ (business)
Identity document

Requirements may change based on regulatory updates. Always check the current requirements using the API before purchasing.

Best Practices

Prepare Documents First

Upload and verify documents before attempting to purchase numbers.

Use Verified Addresses

Only verified addresses can be used for purchases. Allow time for verification.

Keep Documents Current

Ensure documents are not expired and information is up to date.

Check Requirements Early

Query requirements during your planning phase to avoid purchase delays.

Error Handling

Error Code	Description
`requirements_missing`	Purchase requires regulatory requirements not provided
`address_not_found`	Referenced address ID doesn’t exist
`document_not_found`	Referenced document ID doesn’t exist
`address_not_verified`	Address must be verified before use
`document_not_verified`	Document must be verified before use
`invalid_requirement_type`	Requirement type ID is not valid for this purchase

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Regulatory Requirements

Overview

Checking Requirements

Requirement Types

Response

Creating Addresses

Address Fields

Address Statuses

Uploading Documents

Supported Document Types

File Requirements

Document Statuses

Purchasing with Requirements

Managing Addresses

List Addresses

Delete Address

Managing Documents

List Documents

Delete Document

Country-Specific Requirements

Germany (DE)

United Kingdom (GB)

France (FR)

Mexico (MX)

Brazil (BR)

Best Practices

Prepare Documents First

Use Verified Addresses

Keep Documents Current

Check Requirements Early

Error Handling

Next Steps

Purchase Phone Numbers

Create Senders

​Overview

​Checking Requirements

​Requirement Types

​Response

​Creating Addresses

​Address Fields

​Address Statuses

​Uploading Documents

​Supported Document Types

​File Requirements

​Document Statuses

​Purchasing with Requirements

​Managing Addresses

​List Addresses

​Delete Address

​Managing Documents

​List Documents

​Delete Document

​Country-Specific Requirements

​Germany (DE)

​United Kingdom (GB)

​France (FR)

​Mexico (MX)

​Brazil (BR)

​Best Practices

Prepare Documents First

Use Verified Addresses

Keep Documents Current

Check Requirements Early

​Error Handling

​Next Steps

Purchase Phone Numbers

Create Senders

Overview

Checking Requirements

Requirement Types

Response

Creating Addresses

Address Fields

Address Statuses

Uploading Documents

Supported Document Types

File Requirements

Document Statuses

Purchasing with Requirements

Managing Addresses

List Addresses

Delete Address

Managing Documents

List Documents

Delete Document

Country-Specific Requirements

Germany (DE)

United Kingdom (GB)

France (FR)

Mexico (MX)

Brazil (BR)

Best Practices

Error Handling

Next Steps