Regulatory Requirements

Some phone numbers require regulatory information before they can be used: an address, an identity or business document, or text such as a business name. Which numbers do is decided per number by the carrier, not by a fixed list of countries, and the purchase checks it for the exact number you buy, before anything is charged.

Overview

To buy a number with regulatory requirements:

Check requirements for the number you want to buy
Create addresses for any address requirement
Upload documents for any document requirement
Purchase the number with its type, passing every requirement as regulatoryRequirements
Wait for review: the number is yours immediately with regulatoryStatus: pending_review, and can send messages and place calls once it is approved
Assign it to a sender, before or after approval

The information is kept for your project under the number’s country and type. A later purchase in the same country and type may omit regulatoryRequirements, as long as what is kept still covers that number’s requirements.

Checking Requirements

Before purchasing, check what requirements apply. Pass phoneNumber with a number from GET /v1/phone-numbers/available to get the requirements for that exact number, which is what the purchase checks. Encode its + as %2B. countryCode and type give the requirements for a country instead:

curl "https://api.zavu.dev/v1/phone-numbers/requirements?phoneNumber=%2B4930123456" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

An empty items array means the number needs nothing: buy it normally. When the number’s own requirements cannot be resolved, the list for its country and type is returned instead, and the purchase checks the same list. If the requirements cannot be retrieved at all, the API answers 502 with code requirements_unavailable instead of an empty list: retry rather than purchasing without them. For US and Canadian numbers a purchase does not wait on this lookup: they are sold as numbers without requirements. The SDKs below take countryCode and type; they have no per-number variant yet:

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: "DE",
	Type:        zavudev.PhoneNumberTypeLocal,
})

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`	An address: create one and pass its `id`
`document`	An identity or business document: upload one and pass its `id`
`textual`	Text (e.g. a business name): pass the text itself
`action`	An instruction to follow; send no entry for it

Response

{
  "items": [
    {
      "id": "+4930123456",
      "countryCode": "DE",
      "phoneNumberType": "local",
      "action": "ordering",
      "requirementTypes": [
        {
          "id": "8c5b1a2e-0f3d-4f5b-9a61-2c7e4d9b1f10",
          "name": "Address",
          "description": "An address within Germany",
          "type": "address"
        },
        {
          "id": "3f9e2d41-7b6a-4c1e-8d52-9a0b1c2d3e4f",
          "name": "Identity Document",
          "description": "Government-issued ID",
          "type": "document"
        }
      ]
    }
  ]
}

For a phoneNumber request, id is that phone number. For a country request it identifies the requirement group. acceptanceCriteria, when present, carries allowedValues on a phoneNumber request, and minLength, maxLength and allowedValues on a country request.

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.address.id);
console.log("Status:", address.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.address.id)
print("Status:", address.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.address.id}"
puts "Status: #{address.address.status}"

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

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

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

echo "Address ID: {$address->address->id}\n";
echo "Status: {$address->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

firstName and lastName are required. Requests that omit them are refused with 400 invalid_request: the carrier will not register an address without a named person, and an address it refuses cannot be used to buy a number. The SDKs still type both as optional until their next release, so a call that leaves them out compiles and fails at runtime.

Field	Type	Required	Description
`firstName`	string	Yes	First name of the person the address is registered to
`lastName`	string	Yes	Last name of the person the address is registered to
`businessName`	string	No	Business name, for a business address. Defaults to the person’s full name
`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 Status

A new address is returned with status: pending and stays that way. You can use its id in a purchase right away, in the same project it was created in. Review happens on the purchase, not on the address: follow it with the number’s regulatoryStatus. An address marked rejected is refused in a purchase.

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 the returned URL
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.document.id);
console.log("Status:", document.document.status);

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

# Step 2: Upload the file to the returned URL
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.document.id)
print("Status:", document.document.status)

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

# Step 2: Upload the file to the returned URL
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.document.id}"
puts "Status: #{document.document.status}"

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

// Step 2: Upload the file to the returned URL
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.RegulatoryDocumentNewParams{
	Name:         "John Doe Passport",
	DocumentType: zavudev.RegulatoryDocumentNewParamsDocumentTypePassport,
	StorageID:    uploadResp.StorageID,
	MimeType:     "image/jpeg",
	FileSize:     int64(len(fileData)),
})

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

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

// Step 2: Upload the file to the returned URL
$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(
    documentType: 'passport',
    fileSize: strlen($fileData),
    mimeType: 'image/jpeg',
    name: 'John Doe Passport',
    storageID: $storageId,
);

echo "Document ID: {$document->document->id}\n";
echo "Status: {$document->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

The API does not check the file’s format or size; the dashboard uploader accepts the following, so stay within it:

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

Document Status

A new document is returned with status: uploaded and stays that way. You can use its id in a purchase right away, in the project it was uploaded to. Review happens on the purchase, not on the document: follow it with the number’s regulatoryStatus. A document marked rejected is refused in a purchase.

Purchasing with Requirements

Pass one entry per requirement except action ones: requirementType is the requirementTypes[].id from the requirements response, and fieldValue is the address id, the document id, or the text. type is required alongside, the type you searched the number under. Every required id must be present, once, no unknown id may be sent, and addresses and documents must belong to the project making the purchase and must not be rejected. Otherwise the purchase is refused with 400 invalid_request, naming the requirement, before anything is charged. The same happens if an address or document cannot be registered for review.

cURL

curl -X POST https://api.zavu.dev/v1/phone-numbers \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+4930123456",
    "name": "Germany Line",
    "type": "local",
    "regulatoryRequirements": [
      { "requirementType": "8c5b1a2e-0f3d-4f5b-9a61-2c7e4d9b1f10", "fieldValue": "<address id>" },
      { "requirementType": "3f9e2d41-7b6a-4c1e-8d52-9a0b1c2d3e4f", "fieldValue": "<document id>" }
    ]
  }'

regulatoryRequirements and type are new on this endpoint and not yet in the SDKs. Use the REST call above until the SDKs are updated.

The response is the purchased number. It is billed from purchase, and cannot send messages or place calls until review approves it:

{
  "phoneNumber": {
    "id": "pn_abc123",
    "phoneNumber": "+4930123456",
    "status": "active",
    "regulatoryStatus": "pending_review"
  }
}

The status is re-checked every 6 hours. Poll GET /v1/phone-numbers/{phoneNumberId} until regulatoryStatus is approved or rejected.

Assigning a Sender

Assign the number to a sender to use it, before or after approval:

cURL

curl -X PATCH https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "senderId": "snd_abc123" }'

Assigned while pending_review, the number is recorded on the sender and connected when it is approved; if that connection fails it is retried until it succeeds. A sender created over the API is set up for SMS as part of the assignment. A rejected number cannot be assigned: the call answers 400. A number that stays pending_review for long may be waiting on information the API cannot supply: contact support.

Reusing Submitted Information

If the number needs regulatory information and the request carries none, the purchase reuses what your project submitted before for the same country and type, but only when it still covers every requirement of the new number and every address and document in it belongs to the project. Otherwise it is refused with 400 regulatory_compliance_required, listing the missing requirements in details.missingRequirements, and nothing is charged.

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"

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

Requirements differ by country and number type, and change with regulation. The requirements endpoint is the source of truth: query it for the number you are about to buy rather than relying on a fixed list.

Best Practices

Prepare Documents First

Create addresses and upload documents before the purchase call, so it carries every requirement.

Follow the Review

A regulated number is billed from purchase but usable only once regulatoryStatus is approved.

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

Status	Code	Description
`400`	`regulatory_compliance_required`	The number needs regulatory information and none was provided or reusable. `details.missingRequirements` lists what to send
`400`	`invalid_request`	Malformed request, a missing, unknown or repeated requirement id, an address or document from another project or rejected in review, one that could not be registered for review, `type` missing with `regulatoryRequirements`, or requirements that cannot be looked up for this input
`400`	`number_unavailable`	The number is no longer available, or is not listed under the `type` sent
`502`	`requirements_unavailable`	The requirements lookup failed. Retry; it does not mean nothing is required. A purchase refused this way is not charged. A purchase of a US or Canadian number does not return it, because it goes ahead as a number without requirements; this endpoint returns it for any country

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Regulatory Requirements

Overview

Checking Requirements

Requirement Types

Response

Creating Addresses

Address Fields

Address Status

Uploading Documents

Supported Document Types

File Requirements

Document Status

Purchasing with Requirements

Assigning a Sender

Reusing Submitted Information

Managing Addresses

List Addresses

Delete Address

Managing Documents

List Documents

Delete Document

Country-Specific Requirements

Best Practices

Prepare Documents First

Follow the Review

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 Status

​Uploading Documents

​Supported Document Types

​File Requirements

​Document Status

​Purchasing with Requirements

​Assigning a Sender

​Reusing Submitted Information

​Managing Addresses

​List Addresses

​Delete Address

​Managing Documents

​List Documents

​Delete Document

​Country-Specific Requirements

​Best Practices

Prepare Documents First

Follow the Review

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 Status

Uploading Documents

Supported Document Types

File Requirements

Document Status

Purchasing with Requirements

Assigning a Sender

Reusing Submitted Information

Managing Addresses

List Addresses

Delete Address

Managing Documents

List Documents

Delete Document

Country-Specific Requirements

Best Practices

Error Handling

Next Steps