From twilio-developer-kit
Manage regulatory compliance for international phone numbers. Covers what bundles are, which countries require them, how to create End-Users and Supporting Documents, evaluate and submit bundles, fix evaluation failures, update bundles when regulations change, and ISV multi-account patterns. Use this skill when provisioning numbers outside the US.
npx claudepluginhub twilio/ai --plugin twilio-developer-kitThis skill uses the workspace's default tool permissions.
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.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
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.
| Resource | What it is |
|---|---|
| Regulation | Country-specific requirement defining what End-User types and document types are needed |
| Bundle | Container that holds an End-User + Supporting Documents for a specific regulation |
| End-User | The entity answering calls or receiving messages (individual or business type) |
| Supporting Document | Identity/address verification documents (business registration, proof of address, etc.) |
| Evaluation | Synchronous check that validates a bundle against its regulation before submission |
| Item Assignment | Links an End-User or Supporting Document to a Bundle |
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']}")
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()
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()
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)
)
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)
)
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
)
When regulations change, you'll receive an email. Update without deprovisioning numbers:
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
If managing Twilio subaccounts for multiple customers:
Docs: Bundle Clones
EndUserType in the Regulation.twilio-numbers-senderstwilio-compliance-onboarding