Skip to content Skip to navigation Skip to topbar

Page tools

On this page

Looking for more inspiration?Visit the

Getting Started: Regulatory Compliance Public REST APIs

v2 RC APIs Workflow

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.

Flowchart of regulatory bundle workflow from draft to third-party acceptance or rejection.

Read a Regulation of a Bundle

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 .

Query parameters

Property nameTypeRequiredPIIDescription

endUserTypeenum<string>

Optional

The type of End User the regulation requires - can be individual or business.

Possible values:

individualbusiness

isoCountrystring

Optional

The ISO country code of the phone number's country.

numberTypestring

Optional

The type of phone number that the regulatory requiremnt is restricting.

includeConstraintsboolean

Optional

A boolean parameter indicating whether to include constraints or not for supporting end user, documents and their fields

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

Read a Regulation

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listRegulation() {
11  const regulations =
12    await client.numbers.v2.regulatoryCompliance.regulations.list({
13      endUserType: "individual",
14      isoCountry: "au",
15      numberType: "local",
16      limit: 20,
17    });
18
19  regulations.forEach((r) => console.log(r.sid));
20}
21
22listRegulation();

Response

1{
2  "results": [
3    {
4      "sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "friendly_name": "Australia: Local - Individual",
6      "iso_country": "AU",
7      "number_type": "local",
8      "end_user_type": "individual",
9      "requirements": {
10        "end_user": [
11          {
12            "name": "Individual",
13            "type": "individual",
14            "requirement_name": "individual_info",
15            "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/individual",
16            "fields": [
17              "first_name",
18              "last_name"
19            ],
20            "detailed_fields": [
21              {
22                "machine_name": "first_name",
23                "friendly_name": "First Name",
24                "description": "First name of the Individual"
25              },
26              {
27                "machine_name": "last_name",
28                "friendly_name": "Last Name",
29                "description": "Last name of the Individual"
30              }
31            ]
32          }
33        ],
34        "supporting_document": [
35          [
36            {
37              "name": "Address",
38              "type": "document",
39              "requirement_name": "proof_of_address",
40              "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.",
41              "accepted_documents": [
42                {
43                  "name": "Address Validation",
44                  "type": "address",
45                  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/DocumentTypes/address",
46                  "fields": [
47                    "address_sids"
48                  ],
49                  "detailed_fields": [
50                    {
51                      "machine_name": "address_sids",
52                      "friendly_name": "Address sid(s)",
53                      "description": "Address sid of the individual"
54                    }
55                  ]
56                }
57              ]
58            }
59          ]
60        ]
61      },
62      "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
63    }
64  ],
65  "meta": {
66    "page": 0,
67    "page_size": 50,
68    "first_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
69    "previous_page_url": null,
70    "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
71    "next_page_url": null,
72    "key": "results"
73  }
74}

Create a new Regulatory Bundles

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.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

friendlyNamestring

required

The string that you assigned to describe the resource.

emailstring

required

The email address that will receive updates when the Bundle resource changes status.

statusCallbackstring<uri>

Optional

The URL we call to inform your application of status changes.

regulationSidSID<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

isoCountrystring

Optional

The ISO country code of the Bundle's phone number country ownership request.

endUserTypeenum<string>

Optional

Possible values:

individualbusiness

numberTypestring

Optional

The type of phone number of the Bundle's ownership request. Can be local, mobile, national, or toll-free.

isTestboolean

Optional

Indicates that Bundle is a Test Bundle and will be Auto-Rejected

Create a new Bundle

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createBundle() {
11  const bundle = await client.numbers.v2.regulatoryCompliance.bundles.create({
12    email: "numbers-regulatory-review@twilio.com",
13    endUserType: "business",
14    friendlyName: "Twilio GmbH",
15    isoCountry: "de",
16    numberType: "local",
17    statusCallback: "https://my.status.callback.com",
18  });
19
20  console.log(bundle.sid);
21}
22
23createBundle();

Response

1{
2  "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "friendly_name": "Twilio GmbH",
6  "status": "draft",
7  "email": "numbers-regulatory-review@twilio.com",
8  "status_callback": "https://my.status.callback.com",
9  "valid_until": null,
10  "date_created": "2019-07-30T22:29:24Z",
11  "date_updated": "2019-07-31T01:09:00Z",
12  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "links": {
14    "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
15    "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",
16    "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"
17  }
18}

Create a new End-User

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.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

friendlyNamestring

required

The string that you assigned to describe the resource.

typeenum<string>

required

The type of end user of the Bundle resource - can be individual or business.

Possible values:

individualbusiness

attributes

Optional

PII MTL: 30 days

The set of parameters that are the attributes of the End User resource which are derived End User Types.

Create a new End-User

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createEndUser() {
11  const endUser = await client.numbers.v2.regulatoryCompliance.endUsers.create({
12    attributes: {
13      business_name: "Twilio",
14    },
15    friendlyName: "Twilio GmbH",
16    type: "business",
17  });
18
19  console.log(endUser.sid);
20}
21
22createEndUser();

Response

1{
2  "sid": "ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "friendly_name": "Twilio GmbH",
5  "type": "business",
6  "attributes": {
7    "email": "foobar@twilio.com"
8  },
9  "date_created": "2019-07-30T21:57:45Z",
10  "date_updated": "2019-07-30T21:57:45Z",
11  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/EndUsers/ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
12}

Create a new Supporting Document

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.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

friendlyNamestring

required

The string that you assigned to describe the resource.

typestring

required

The type of the Supporting Document.

attributes

Optional

PII MTL: 30 days

The set of parameters that are the attributes of the Supporting Documents resource which are derived Supporting Document Types.

Create a new Supporting Document

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createSupportingDocument() {
11  const supportingDocument =
12    await client.numbers.v2.regulatoryCompliance.supportingDocuments.create({
13      attributes: {
14        registered_seat_of_business:
15          "375 Beale St, San Francisco 94133, California USA",
16        document_number: "4389237",
17        business_name: "Twilio",
18        issue_date: "2020-12-05",
19      },
20      friendlyName: "TwilioBusinessRegistration",
21      type: "business_registration",
22    });
23
24  console.log(supportingDocument.sid);
25}
26
27createSupportingDocument();

Response

1{
2  "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "friendly_name": "TwilioBusinessRegistration",
5  "mime_type": "mime_type",
6  "status": "draft",
7  "failure_reason": null,
8  "errors": null,
9  "type": "business_registration",
10  "attributes": {
11    "first_name": "foo",
12    "last_name": "bar"
13  },
14  "date_created": "2019-07-31T02:11:52Z",
15  "date_updated": "2019-07-31T02:11:52Z",
16  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
17}

Create a new Supporting Document with file upload

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.

Create a Supporting Document with a file upload

1ATTRIBUTES=$(cat << EOF
2{
3    "address_sids": ["ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
4    "document_number": "312454", 
5    "business_name": "Twilio",
6    "issue_date": "2019-11-15"
7}
8EOF
9)
10
11curl -X POST https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments \
12-F "Attributes=$ATTRIBUTES" \
13-F "FriendlyName=Twilio GmbH" \
14-F "Type=business_registration" \
15-F "File=@twilio_business_registration.png" \
16-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

Output

1{
2    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3    "attributes": {
4        "business_name": "Twilio",
5        "document_number": "312454",
6        "issue_date": "2019-11-15",
7        "registered_seat_of_business": "San Francisco, CA, USA"
8    },
9    "date_created": "2019-10-17T17:06:47Z",
10    "date_updated": "2019-10-17T17:06:47Z",
11    "friendly_name": "Twilio GmbH",
12    "mime_type": "image/png",
13    "sid": "RDd6340f49f352d06b77e7017d93591483",
14    "status": "draft",
15    "type": "business_registration",
16    "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Documents/RDd6340f49f352d06b77e7017d93591483"
17}

Create an Item Assignment of a Bundle

Once you have created all the various End-User, Supporting Documents, and Addresses, the next step is to Assign Items to the Regulatory Bundle.

Path parameters

Property nameTypeRequiredPIIDescription

bundleSidSID<BU>

required

The unique string that we created to identify the Bundle resource.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

objectSidSID

required

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

Assign Items to a Regulatory Bundle

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createItemAssignment() {
11  const itemAssignment = await client.numbers.v2.regulatoryCompliance
12    .bundles("BUe6c04e6a1a6133a9d3d2314e38f51dfb")
13    .itemAssignments.create({
14      objectSid: "RD70f07ace005177cbfee907bc9c1acabd",
15    });
16
17  console.log(itemAssignment.bundleSid);
18}
19
20createItemAssignment();

Response

1{
2  "sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "bundle_sid": "BUe6c04e6a1a6133a9d3d2314e38f51dfb",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "object_sid": "RD70f07ace005177cbfee907bc9c1acabd",
6  "date_created": "2019-07-31T02:34:41Z",
7  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
8}

Submit Regulatory Bundle

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.

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<BU>

required

The unique string that we created to identify the Bundle resource.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

statusenum<string>

Optional

The verification status of the Bundle resource.

Possible values:

draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved

statusCallbackstring<uri>

Optional

The URL we call to inform your application of status changes.

friendlyNamestring

Optional

The string that you assigned to describe the resource.

emailstring

Optional

The email address that will receive updates when the Bundle resource changes status.

Submit Regulatory Bundle

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateBundle() {
11  const bundle = await client.numbers.v2.regulatoryCompliance
12    .bundles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({ status: "pending-review" });
14
15  console.log(bundle.sid);
16}
17
18updateBundle();

Response

1{
2  "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "friendly_name": "friendly_name",
6  "status": "pending-review",
7  "email": "email",
8  "status_callback": "http://www.example.com",
9  "valid_until": null,
10  "date_created": "2019-07-30T22:29:24Z",
11  "date_updated": "2019-07-31T01:09:00Z",
12  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "links": {
14    "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
15    "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",
16    "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"
17  }
18}