twilio-regulatory-compliance-bundles

Overview

Phone numbers are national resources — many countries require identity verification of the end-user before provisioning. A Regulatory Bundle is a container holding an End-User record + Supporting Documents that proves your right to use numbers in a specific country.

Not all countries require bundles — check the Regulatory Guidelines page for country-specific requirements. If a country requires a bundle, provisioning fails without one.

Key Concepts

Quickstart: Provision a Number with a Bundle

Step 1 — Query the Regulation

Find out what's required for the country and number type:

Python

import os, requests

account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]

# What does Germany require for local business numbers?
regulations = requests.get(
    "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations",
    params={"IsoCountry": "DE", "NumberType": "local", "EndUserType": "business"},
    auth=(account_sid, auth_token)
).json()

for reg in regulations["results"]:
    print(f"Regulation: {reg['sid']}")
    print(f"Requirements: {reg['requirements']}")

Step 2 — Create an End-User

Python

end_user = requests.post(
    "https://numbers.twilio.com/v2/RegulatoryCompliance/EndUsers",
    data={
        "FriendlyName": "Acme GmbH",
        "Type": "business",
        "Attributes": '{"business_name": "Acme GmbH", "business_registration_number": "HRB12345"}'
    },
    auth=(account_sid, auth_token)
).json()

Step 3 — Upload Supporting Documents

Python

document = requests.post(
    "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments",
    data={
        "FriendlyName": "Acme Business Registration",
        "Type": "business_registration",
        "Attributes": '{"business_name": "Acme GmbH"}'
    },
    auth=(account_sid, auth_token)
).json()

Step 4 — Create a Bundle and Assign Items

Python

# Create the bundle
bundle = requests.post(
    "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles",
    data={
        "FriendlyName": "Germany Local - Acme",
        "RegulationSid": regulations["results"][0]["sid"],
        "IsoCountry": "DE",
        "EndUserType": "business",
        "Email": "compliance@acme.com"
    },
    auth=(account_sid, auth_token)
).json()

bundle_sid = bundle["sid"]

# Assign End-User to bundle
requests.post(
    f"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/ItemAssignments",
    data={"ObjectSid": end_user["sid"]},
    auth=(account_sid, auth_token)
)

# Assign Supporting Document to bundle
requests.post(
    f"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/ItemAssignments",
    data={"ObjectSid": document["sid"]},
    auth=(account_sid, auth_token)
)

Step 5 — Evaluate and Submit

Python

# Run evaluation (synchronous — returns field-level failures)
evaluation = requests.post(
    f"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/Evaluations",
    auth=(account_sid, auth_token)
).json()

if evaluation["status"] == "noncompliant":
    for violation in evaluation["results"]:
        print(f"Field: {violation['friendly_name']} — {violation['description']}")
    # Fix the issues, then re-evaluate
else:
    # Submit for review
    requests.post(
        f"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}",
        data={"Status": "pending-review"},
        auth=(account_sid, auth_token)
    )

Step 6 — Provision Number with Bundle

Once the bundle is approved:

Python

from twilio.rest import Client
client = Client(account_sid, auth_token)

number = client.incoming_phone_numbers.create(
    phone_number="+4930xxxxxxx",
    bundle_sid=bundle_sid
)

Updating an Approved Bundle

When regulations change, you'll receive an email. Update without deprovisioning numbers:

1. Copy the approved bundle into a mutable state via the Bundle Copies resource
2. Update the End-User or Supporting Document on the copy
3. Re-evaluate the copy
4. Replace items in the original bundle via the Replace Items resource

Phone numbers remain provisioned throughout this process.

Alternative: Create a new bundle → get it approved → remap numbers to the new bundle.

Docs: Bundle Copies | Replace Items

ISV / Multi-Account Pattern

If managing Twilio subaccounts for multiple customers:

• Each customer needs their own bundle — Do not reuse your business information in customer bundles
• Use the Bundle Clones resource to duplicate bundle structures across subaccounts
• End-User records must reflect the actual end-user (your customer), not you

Docs: Bundle Clones

CANNOT

• Cannot provision numbers without required bundles — Provisioning fails immediately. Check Regulations resource first.
• Cannot reuse one bundle across different number types — Each bundle is tied to a specific regulation (country + number type + end-user type).
• Locality-matching addresses required in ~33 countries — Germany (and others) require the End-User address to be within the region of the phone number prefix, not just any address in the country. US HQ address will fail for a Berlin number.
• Cannot hardcode regulation requirements — Regulations change periodically. Always query the Regulations resource dynamically.
• Do not create a new bundle when evaluation fails — Fix the existing bundle. Creating new ones wastes time and clutters your account.
• Cannot reuse your ISV info in customer bundles — Bundles must represent the actual end-user. Twilio audits this.
• Some markets are business-only — Individual provisioning not allowed. Check the EndUserType in the Regulation.

Next Steps

• Choose number type before provisioning: twilio-numbers-senders
• Register numbers after provisioning: twilio-compliance-onboarding
• Country-specific requirements: Regulatory Guidelines
• API reference: Regulatory Compliance API