Update to Twilio Developer Kit

{
  "name": "twilio-regulatory-compliance-bundles",
  "description": "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 253
    }
  ],
  "skill_md_contents": "---\nname: twilio-regulatory-compliance-bundles\ndescription: >\n  Manage regulatory compliance for international phone numbers. Covers\n  what bundles are, which countries require them, how to create End-Users\n  and Supporting Documents, evaluate and submit bundles, fix evaluation\n  failures, update bundles when regulations change, and ISV multi-account\n  patterns. Use this skill when provisioning numbers outside the US.\n---\n\n## Overview\n\nPhone 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.\n\n**Not all countries require bundles** — check the [Regulatory Guidelines page](https://www.twilio.com/en-us/guidelines/regulatory) for country-specific requirements. If a country requires a bundle, provisioning fails without one.\n\n---\n\n## Key Concepts\n\n| Resource | What it is |\n|----------|-----------|\n| **Regulation** | Country-specific requirement defining what End-User types and document types are needed |\n| **Bundle** | Container that holds an End-User + Supporting Documents for a specific regulation |\n| **End-User** | The entity answering calls or receiving messages (`individual` or `business` type) |\n| **Supporting Document** | Identity/address verification documents (business registration, proof of address, etc.) |\n| **Evaluation** | Synchronous check that validates a bundle against its regulation before submission |\n| **Item Assignment** | Links an End-User or Supporting Document to a Bundle |\n\n---\n\n## Quickstart: Provision a Number with a Bundle\n\n### Step 1 — Query the Regulation\n\nFind out what's required for the country and number type:\n\n**Python**\n```python\nimport os, requests\n\naccount_sid = os.environ[\"TWILIO_ACCOUNT_SID\"]\nauth_token = os.environ[\"TWILIO_AUTH_TOKEN\"]\n\n# What does Germany require for local business numbers?\nregulations = requests.get(\n    \"https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations\",\n    params={\"IsoCountry\": \"DE\", \"NumberType\": \"local\", \"EndUserType\": \"business\"},\n    auth=(account_sid, auth_token)\n).json()\n\nfor reg in regulations[\"results\"]:\n    print(f\"Regulation: {reg['sid']}\")\n    print(f\"Requirements: {reg['requirements']}\")\n```\n\n### Step 2 — Create an End-User\n\n**Python**\n```python\nend_user = requests.post(\n    \"https://numbers.twilio.com/v2/RegulatoryCompliance/EndUsers\",\n    data={\n        \"FriendlyName\": \"Acme GmbH\",\n        \"Type\": \"business\",\n        \"Attributes\": '{\"business_name\": \"Acme GmbH\", \"business_registration_number\": \"HRB12345\"}'\n    },\n    auth=(account_sid, auth_token)\n).json()\n```\n\n### Step 3 — Upload Supporting Documents\n\n**Python**\n```python\ndocument = requests.post(\n    \"https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments\",\n    data={\n        \"FriendlyName\": \"Acme Business Registration\",\n        \"Type\": \"business_registration\",\n        \"Attributes\": '{\"business_name\": \"Acme GmbH\"}'\n    },\n    auth=(account_sid, auth_token)\n).json()\n```\n\n### Step 4 — Create a Bundle and Assign Items\n\n**Python**\n```python\n# Create the bundle\nbundle = requests.post(\n    \"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles\",\n    data={\n        \"FriendlyName\": \"Germany Local - Acme\",\n        \"RegulationSid\": regulations[\"results\"][0][\"sid\"],\n        \"IsoCountry\": \"DE\",\n        \"EndUserType\": \"business\",\n        \"Email\": \"compliance@acme.com\"\n    },\n    auth=(account_sid, auth_token)\n).json()\n\nbundle_sid = bundle[\"sid\"]\n\n# Assign End-User to bundle\nrequests.post(\n    f\"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/ItemAssignments\",\n    data={\"ObjectSid\": end_user[\"sid\"]},\n    auth=(account_sid, auth_token)\n)\n\n# Assign Supporting Document to bundle\nrequests.post(\n    f\"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/ItemAssignments\",\n    data={\"ObjectSid\": document[\"sid\"]},\n    auth=(account_sid, auth_token)\n)\n```\n\n### Step 5 — Evaluate and Submit\n\n**Python**\n```python\n# Run evaluation (synchronous — returns field-level failures)\nevaluation = requests.post(\n    f\"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}/Evaluations\",\n    auth=(account_sid, auth_token)\n).json()\n\nif evaluation[\"status\"] == \"noncompliant\":\n    for violation in evaluation[\"results\"]:\n        print(f\"Field: {violation['friendly_name']} — {violation['description']}\")\n    # Fix the issues, then re-evaluate\nelse:\n    # Submit for review\n    requests.post(\n        f\"https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/{bundle_sid}\",\n        data={\"Status\": \"pending-review\"},\n        auth=(account_sid, auth_token)\n    )\n```\n\n### Step 6 — Provision Number with Bundle\n\nOnce the bundle is approved:\n\n**Python**\n```python\nfrom twilio.rest import Client\nclient = Client(account_sid, auth_token)\n\nnumber = client.incoming_phone_numbers.create(\n    phone_number=\"+4930xxxxxxx\",\n    bundle_sid=bundle_sid\n)\n```\n\n---\n\n## Updating an Approved Bundle\n\nWhen regulations change, you'll receive an email. Update without deprovisioning numbers:\n\n1. **Copy** the approved bundle into a mutable state via the Bundle Copies resource\n2. **Update** the End-User or Supporting Document on the copy\n3. **Re-evaluate** the copy\n4. **Replace** items in the original bundle via the Replace Items resource\n\nPhone numbers remain provisioned throughout this process.\n\n**Alternative:** Create a new bundle → get it approved → remap numbers to the new bundle.\n\n**Docs:** [Bundle Copies](https://www.twilio.com/docs/phone-numbers/regulatory/api/bundles-copies) | [Replace Items](https://www.twilio.com/docs/phone-numbers/regulatory/api/bundles-replace-items)\n\n---\n\n## ISV / Multi-Account Pattern\n\nIf managing Twilio subaccounts for multiple customers:\n\n- **Each customer needs their own bundle** — Do not reuse your business information in customer bundles\n- Use the **Bundle Clones** resource to duplicate bundle structures across subaccounts\n- End-User records must reflect the actual end-user (your customer), not you\n\n**Docs:** [Bundle Clones](https://www.twilio.com/docs/phone-numbers/regulatory/api/bundles-clones)\n\n---\n\n## CANNOT\n\n- **Cannot provision numbers without required bundles** — Provisioning fails immediately. Check Regulations resource first.\n- **Cannot reuse one bundle across different number types** — Each bundle is tied to a specific regulation (country + number type + end-user type).\n- **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.\n- **Cannot hardcode regulation requirements** — Regulations change periodically. Always query the Regulations resource dynamically.\n- **Do not create a new bundle when evaluation fails** — Fix the existing bundle. Creating new ones wastes time and clutters your account.\n- **Cannot reuse your ISV info in customer bundles** — Bundles must represent the actual end-user. Twilio audits this.\n- **Some markets are business-only** — Individual provisioning not allowed. Check the `EndUserType` in the Regulation.\n\n---\n\n## Next Steps\n\n- **Choose number type before provisioning:** `twilio-numbers-senders`\n- **Register numbers after provisioning:** `twilio-compliance-onboarding`\n- **Country-specific requirements:** [Regulatory Guidelines](https://www.twilio.com/en-us/guidelines/regulatory)\n- **API reference:** [Regulatory Compliance API](https://www.twilio.com/docs/phone-numbers/regulatory/api)\n"
}