Getting Started: Regulatory Compliance Public REST APIs Warning The v2 Regulatory Compliance APIs are in Public Beta. No changes in the API contract will occur when the API moves from Public Beta to GA.
In the new v2 service, many of the objects will be re-usable. The re-usability of objects allows you to build and construct Regulatory Bundles at scale without having to create the same End-User or Supporting Document for each number group that you wish to lease.
The workflow for v2 below depicts both the Regulatory Bundles and Supporting Documents state machines. These workflows are crucial to providing a scalable and transparent process for both Twilio's customers and Twilio's customer's end-users through critical PII abstraction.
Before creating a new Regulatory Bundle, you will need to understand the requirements of a Regulation.
A Regulation instance unique per IsoCountry, NumberType, and EndUserType .
Property name Type Required PII Description
EndUserType enum<string> Optional The type of End User the regulation requires - can be individual or business.
Possible values: individualbusiness
The ISO country code of the phone number's country.
The type of phone number that the regulatory requiremnt is restricting.
IncludeConstraints boolean Optional A boolean parameter indicating whether to include constraints or not for supporting end user, documents and their fields
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Minimum: 1Maximum: 1000
The page index. This value is simply for client state.
Minimum: 0
The page token. This is provided by the API.
_22 // Download the helper library from https://www.twilio.com/docs/node/install
_22 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22 // Find your Account SID and Auth Token at twilio.com/console
_22 // and set the environment variables. See http://twil.io/secure
_22 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22 const authToken = process.env.TWILIO_AUTH_TOKEN;
_22 const client = twilio(accountSid, authToken);
_22 async function listRegulation() {
_22 await client.numbers.v2.regulatoryCompliance.regulations.list({
_22 endUserType: "individual",
_22 regulations.forEach((r) => console.log(r.sid));
_74 "sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_74 "friendly_name": "Australia: Local - Individual",
_74 "number_type": "local",
_74 "end_user_type": "individual",
_74 "name": "Individual",
_74 "type": "individual",
_74 "requirement_name": "individual_info",
_74 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/individual",
_74 "machine_name": "first_name",
_74 "friendly_name": "First Name",
_74 "description": "First name of the Individual"
_74 "machine_name": "last_name",
_74 "friendly_name": "Last Name",
_74 "description": "Last name of the Individual"
_74 "supporting_document": [
_74 "requirement_name": "proof_of_address",
_74 "description": "The physical location of the individual or business. Must be within locality or region covered by the phone numbers prefix; a PO Box is not acceptable where a local address is required.",
_74 "accepted_documents": [
_74 "name": "Address Validation",
_74 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/DocumentTypes/address",
_74 "machine_name": "address_sids",
_74 "friendly_name": "Address sid(s)",
_74 "description": "Address sid of the individual"
_74 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_74 "first_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
_74 "previous_page_url": null,
_74 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
_74 "next_page_url": null,
To begin the process of creating a new Regulatory Bundle, you will need to specify either the following three parameters:
IsoCountry, NumberType, and EndUserType
or
the RegulationSid.
Either of those options will provide the metadata required to create the Regulatory Bundle container for Supporting Documents and End-Users to be assigned to.
Property name Type Required PII Description
FriendlyName string required The string that you assigned to describe the resource.
The email address that will receive updates when the Bundle resource changes status.
StatusCallback string<uri> Optional The URL we call to inform your application of status changes.
RegulationSid SID<RN> Optional The unique string of a regulation that is associated to the Bundle resource.
Pattern: ^RN[0-9a-fA-F]{32}$Min length: 34Max length: 34
EndUserType enum<string> Optional The type of phone number of the Bundle's ownership request. Can be local, mobile, national, or toll free.
_23 // Download the helper library from https://www.twilio.com/docs/node/install
_23 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_23 // Find your Account SID and Auth Token at twilio.com/console
_23 // and set the environment variables. See http://twil.io/secure
_23 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_23 const authToken = process.env.TWILIO_AUTH_TOKEN;
_23 const client = twilio(accountSid, authToken);
_23 async function createBundle() {
_23 const bundle = await client.numbers.v2.regulatoryCompliance.bundles.create({
_23 email: "numbers-regulatory-review@twilio.com",
_23 endUserType: "business",
_23 friendlyName: "Twilio GmbH",
_23 statusCallback: "https://my.status.callback.com",
_23 console.log(bundle.sid);
_18 "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "friendly_name": "Twilio GmbH",
_18 "email": "numbers-regulatory-review@twilio.com",
_18 "status_callback": "https://my.status.callback.com",
_18 "date_created": "2019-07-30T22:29:24Z",
_18 "date_updated": "2019-07-31T01:09:00Z",
_18 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
_18 "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",
_18 "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"
Once you successfully create the Bundle, you will either need to create a new End-User. If you have an End-User you've already created that you'd like to use, you can bypass this step.
The End-User is the individual or business that answers the phone call or message - whichever type you selected in the destination Regulatory Bundle container.
The end-user's information will be sent to the regulating body of the phone number's originating country.
Property name Type Required PII Description
FriendlyName string required The string that you assigned to describe the resource.
The type of end user of the Bundle resource - can be individual or business.
Possible values: individualbusiness
The set of parameters that are the attributes of the End User resource which are derived End User Types.
_22 // Download the helper library from https://www.twilio.com/docs/node/install
_22 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22 // Find your Account SID and Auth Token at twilio.com/console
_22 // and set the environment variables. See http://twil.io/secure
_22 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22 const authToken = process.env.TWILIO_AUTH_TOKEN;
_22 const client = twilio(accountSid, authToken);
_22 async function createEndUser() {
_22 const endUser = await client.numbers.v2.regulatoryCompliance.endUsers.create({
_22 business_name: "Twilio",
_22 friendlyName: "Twilio GmbH",
_22 console.log(endUser.sid);
_12 "sid": "ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12 "friendly_name": "Twilio GmbH",
_12 "email": "foobar@twilio.com"
_12 "date_created": "2019-07-30T21:57:45Z",
_12 "date_updated": "2019-07-30T21:57:45Z",
_12 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/EndUsers/ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
For regulated number groups, documentation is required. This supporting documentation can vary from metadata to a file upload requirement.
The Supporting Documents resource allows you to create and manage Supporting Documents that can be assigned to multiple Regulatory Bundle containers.
Property name Type Required PII Description
FriendlyName string required The string that you assigned to describe the resource.
The type of the Supporting Document.
The set of parameters that are the attributes of the Supporting Documents resource which are derived Supporting Document Types.
_27 // Download the helper library from https://www.twilio.com/docs/node/install
_27 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_27 // Find your Account SID and Auth Token at twilio.com/console
_27 // and set the environment variables. See http://twil.io/secure
_27 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_27 const authToken = process.env.TWILIO_AUTH_TOKEN;
_27 const client = twilio(accountSid, authToken);
_27 async function createSupportingDocument() {
_27 const supportingDocument =
_27 await client.numbers.v2.regulatoryCompliance.supportingDocuments.create({
_27 registered_seat_of_business:
_27 "375 Beale St, San Francisco 94133, California USA",
_27 document_number: "4389237",
_27 business_name: "Twilio",
_27 issue_date: "2020-12-05",
_27 friendlyName: "TwilioBusinessRegistration",
_27 type: "business_registration",
_27 console.log(supportingDocument.sid);
_27 createSupportingDocument();
_16 "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "friendly_name": "TwilioBusinessRegistration",
_16 "mime_type": "mime_type",
_16 "failure_reason": null,
_16 "type": "business_registration",
_16 "date_created": "2019-07-31T02:11:52Z",
_16 "date_updated": "2019-07-31T02:11:52Z",
_16 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Some regulations require a Supporting Document to upload proof. Proof for Twilio is the actual document that you would present during an in-person transaction.
The file upload has the same request parameters as the Supporting Document create, but with two significant differences: the base URI should be https://numbers-upload.twilio.com and you'll need to change --data-urlencode to -F as shown in the example.
_16 ATTRIBUTES=$(cat << EOF
_16 "address_sids": ["ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_16 "document_number": "312454",
_16 "business_name": "Twilio",
_16 "issue_date": "2019-11-15"
_16 curl -X POST https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments \
_16 -F "Attributes=$ATTRIBUTES" \
_16 -F "FriendlyName=Twilio GmbH" \
_16 -F "Type=business_registration" \
_16 -F "File=@twilio_business_registration.png" \
_16 -u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "business_name": "Twilio",
_17 "document_number": "312454",
_17 "issue_date": "2019-11-15",
_17 "registered_seat_of_business": "San Francisco, CA, USA"
_17 "date_created": "2019-10-17T17:06:47Z",
_17 "date_updated": "2019-10-17T17:06:47Z",
_17 "friendly_name": "Twilio GmbH",
_17 "mime_type": "image/png",
_17 "sid": "RDd6340f49f352d06b77e7017d93591483",
_17 "type": "business_registration",
_17 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Documents/RDd6340f49f352d06b77e7017d93591483"
Once you have created all the various End-User, Supporting Documents, and Addresses, the next step is to Assign Items to the Regulatory Bundle.
Property name Type Required PII Description
The unique string that we created to identify the Bundle resource.
Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property name Type Required PII Description
The SID of an object bag that holds information of the different items.
Pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$Min length: 34Max length: 34
_20 // Download the helper library from https://www.twilio.com/docs/node/install
_20 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20 // Find your Account SID and Auth Token at twilio.com/console
_20 // and set the environment variables. See http://twil.io/secure
_20 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20 const authToken = process.env.TWILIO_AUTH_TOKEN;
_20 const client = twilio(accountSid, authToken);
_20 async function createItemAssignment() {
_20 const itemAssignment = await client.numbers.v2.regulatoryCompliance
_20 .bundles("BUe6c04e6a1a6133a9d3d2314e38f51dfb")
_20 .itemAssignments.create({
_20 objectSid: "RD70f07ace005177cbfee907bc9c1acabd",
_20 console.log(itemAssignment.bundleSid);
_20 createItemAssignment();
_10 "sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "bundle_sid": "BUe6c04e6a1a6133a9d3d2314e38f51dfb",
_10 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "object_sid": "RD70f07ace005177cbfee907bc9c1acabd",
_10 "date_created": "2019-07-31T02:34:41Z",
_10 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Once you've succeeded in Assigning all the required Items to the Regulatory Bundle, the final step is to submit the Regulatory Bundle for review. The status of the Regulatory Bundle will transition to pending-review.
Property name Type Required PII Description
The unique string that we created to identify the Bundle resource.
Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property name Type Required PII Description
Status enum<string> Optional The verification status of the Bundle resource.
Possible values: draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved
StatusCallback string<uri> Optional The URL we call to inform your application of status changes.
FriendlyName string Optional The string that you assigned to describe the resource.
The email address that will receive updates when the Bundle resource changes status.
_18 // Download the helper library from https://www.twilio.com/docs/node/install
_18 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18 // Find your Account SID and Auth Token at twilio.com/console
_18 // and set the environment variables. See http://twil.io/secure
_18 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18 const authToken = process.env.TWILIO_AUTH_TOKEN;
_18 const client = twilio(accountSid, authToken);
_18 async function updateBundle() {
_18 const bundle = await client.numbers.v2.regulatoryCompliance
_18 .bundles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18 .update({ status: "pending-review" });
_18 console.log(bundle.sid);
_18 "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "friendly_name": "friendly_name",
_18 "status": "pending-review",
_18 "status_callback": "http://www.example.com",
_18 "date_created": "2019-07-30T22:29:24Z",
_18 "date_updated": "2019-07-31T01:09:00Z",
_18 "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
_18 "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",
_18 "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"
