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

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 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);

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

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

Delete Address

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

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

Delete Document

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

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

Concepts

Guides

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

Getting Started

Concepts

Guides

​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