Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Getting Started: Regulatory Compliance Public REST APIs


(warning)

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.


v2 RC APIs Workflow

v2-rc-api page anchor

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.

Regulatory Bundle Workflow.

Read a Regulation of a Bundle

regulation-read page anchor

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 .

URI parameters
EndUserTypetype: enum<STRING>Not PII
Query Parameter

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

Possible values:
individualbusiness

IsoCountrytype: stringNot PII
Query Parameter

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


NumberTypetype: stringNot PII
Query Parameter

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


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Read a Regulation

read-a-regulation page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = require('twilio')(accountSid, authToken);
_16
_16
client.numbers.v2.regulatoryCompliance
_16
.regulations
_16
.list({
_16
isoCountry: 'au',
_16
numberType: 'local',
_16
endUserType: 'individual',
_16
limit: 20
_16
})
_16
.then(regulations => regulations.forEach(r => console.log(r.sid)));

Output

_74
{
_74
"results": [
_74
{
_74
"sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_74
"friendly_name": "Australia: Local - Individual",
_74
"iso_country": "AU",
_74
"number_type": "local",
_74
"end_user_type": "individual",
_74
"requirements": {
_74
"end_user": [
_74
{
_74
"name": "Individual",
_74
"type": "individual",
_74
"requirement_name": "individual_info",
_74
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/individual",
_74
"fields": [
_74
"first_name",
_74
"last_name"
_74
],
_74
"detailed_fields": [
_74
{
_74
"machine_name": "first_name",
_74
"friendly_name": "First Name",
_74
"description": "First name of the Individual"
_74
},
_74
{
_74
"machine_name": "last_name",
_74
"friendly_name": "Last Name",
_74
"description": "Last name of the Individual"
_74
}
_74
]
_74
}
_74
],
_74
"supporting_document": [
_74
[
_74
{
_74
"name": "Address",
_74
"type": "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
{
_74
"name": "Address Validation",
_74
"type": "address",
_74
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/DocumentTypes/address",
_74
"fields": [
_74
"address_sids"
_74
],
_74
"detailed_fields": [
_74
{
_74
"machine_name": "address_sids",
_74
"friendly_name": "Address sid(s)",
_74
"description": "Address sid of the individual"
_74
}
_74
]
_74
}
_74
]
_74
}
_74
]
_74
]
_74
},
_74
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations/RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_74
}
_74
],
_74
"meta": {
_74
"page": 0,
_74
"page_size": 50,
_74
"first_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
_74
"previous_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
_74
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=0",
_74
"next_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Regulations?PageSize=50&Page=1",
_74
"key": "results"
_74
}
_74
}


Create a new Regulatory Bundles

bundle-create page anchor

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
FriendlyNametype: stringNot PII
Required

The string that you assigned to describe the resource.


Emailtype: stringNot PII
Required

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


StatusCallbacktype: string<URI>Not PII

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


RegulationSidtype: SID<RN>Not PII

The unique string of a regulation that is associated to the Bundle resource.


EndUserTypetype: enum<STRING>Not PII
Possible values:
individualbusiness

NumberTypetype: stringNot PII

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_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 = require('twilio')(accountSid, authToken);
_18
_18
client.numbers.v2.regulatoryCompliance
_18
.bundles
_18
.create({
_18
endUserType: 'business',
_18
isoCountry: 'de',
_18
numberType: 'local',
_18
statusCallback: 'https://my.status.callback.com',
_18
friendlyName: 'Twilio GmbH',
_18
email: 'numbers-regulatory-review@twilio.com'
_18
})
_18
.then(bundle => console.log(bundle.sid));

Output

_18
{
_18
"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"regulation_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"friendly_name": "Twilio GmbH",
_18
"status": "draft",
_18
"email": "numbers-regulatory-review@twilio.com",
_18
"status_callback": "https://my.status.callback.com",
_18
"valid_until": null,
_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/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"links": {
_18
"evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",
_18
"item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ItemAssignments",
_18
"bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Copies"
_18
}
_18
}


Create a new End-User

end-user-create page anchor

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
FriendlyNametype: stringNot PII
Required

The string that you assigned to describe the resource.


Typetype: enum<STRING>Not PII
Required

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

Possible values:
individualbusiness

Attributestype: objectPII MTL: 30 days

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.numbers.v2.regulatoryCompliance
_13
.endUsers
_13
.create({attributes: {
_13
business_name: 'Twilio'
_13
}, friendlyName: 'Twilio GmbH', type: 'business'})
_13
.then(end_user => console.log(end_user.sid));

Output

_12
{
_12
"sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12
"friendly_name": "Twilio GmbH",
_12
"type": "business",
_12
"attributes": {
_12
"business_name": "Twilio"
_12
},
_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/ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_12
}


Create a new Supporting Document

supporting-document-create page anchor

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
FriendlyNametype: stringNot PII
Required

The string that you assigned to describe the resource.


Typetype: stringNot PII
Required

The type of the Supporting Document.


Attributestype: objectPII 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

create-a-new-supporting-document page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = require('twilio')(accountSid, authToken);
_16
_16
client.numbers.v2.regulatoryCompliance
_16
.supportingDocuments
_16
.create({attributes: {
_16
registered_seat_of_business: '375 Beale St, San Francisco 94133, California USA',
_16
document_number: '4389237',
_16
business_name: 'Twilio',
_16
issue_date: '2020-12-05'
_16
}, friendlyName: 'TwilioBusinessRegistration', type: 'business_registration'})
_16
.then(supporting_document => console.log(supporting_document.sid));

Output

_18
{
_18
"sid": "RDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"friendly_name": "TwilioBusinessRegistration",
_18
"mime_type": "mime_type",
_18
"status": "draft",
_18
"failure_reason": null,
_18
"type": "business_registration",
_18
"attributes": {
_18
"registered_seat_of_business": "375 Beale St, San Francisco 94133, California USA",
_18
"document_number": "4389237",
_18
"business_name": "Twilio",
_18
"issue_date": "2020-12-05"
_18
},
_18
"date_created": "2019-07-31T02:11:52Z",
_18
"date_updated": "2019-07-31T02:11:52Z",
_18
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_18
}

Create a new Supporting Document with file upload

file-upload page anchor

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

create-a-supporting-document-with-a-file-upload page anchor
curl

_16
ATTRIBUTES=$(cat << EOF
_16
{
_16
"address_sids": ["ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_16
"document_number": "312454",
_16
"business_name": "Twilio",
_16
"issue_date": "2019-11-15"
_16
}
_16
EOF
_16
)
_16
_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

Output

_17
{
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"attributes": {
_17
"business_name": "Twilio",
_17
"document_number": "312454",
_17
"issue_date": "2019-11-15",
_17
"registered_seat_of_business": "San Francisco, CA, USA"
_17
},
_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
"status": "draft",
_17
"type": "business_registration",
_17
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Documents/RDd6340f49f352d06b77e7017d93591483"
_17
}


Create an Item Assignment of a Bundle

item-assignment-create page anchor

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

URI parameters
BundleSidtype: SID<BU>Not PII
Path Parameter

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


Request body parameters
ObjectSidtype: SIDNot PII
Required

The SID of an object bag that holds information of the different items.

Assign Items to a Regulatory Bundle

assign-items-to-a-regulatory-bundle page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = require('twilio')(accountSid, authToken);
_12
_12
client.numbers.v2.regulatoryCompliance
_12
.bundles('BUe6c04e6a1a6133a9d3d2314e38f51dfb')
_12
.itemAssignments
_12
.create({objectSid: 'RD70f07ace005177cbfee907bc9c1acabd'})
_12
.then(item_assignment => console.log(item_assignment.bundleSid));

Output

_10
{
_10
"sid": "BVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"bundle_sid": "BUe6c04e6a1a6133a9d3d2314e38f51dfb",
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"object_sid": "RD70f07ace005177cbfee907bc9c1acabd",
_10
"date_created": "2019-07-31T02:34:41Z",
_10
"url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ItemAssignments/BVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_10
}


Submit Regulatory Bundle

submit-bundle page anchor

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.

URI parameters
Sidtype: SID<BU>Not PII
Path Parameter

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


Request body parameters
Statustype: enum<STRING>Not PII

The verification status of the Bundle resource.

Possible values:
draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved

StatusCallbacktype: string<URI>Not PII

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


FriendlyNametype: stringNot PII

The string that you assigned to describe the resource.


Emailtype: stringNot PII

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

Submit Regulatory Bundle

submit-regulatory-bundle page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.numbers.v2.regulatoryCompliance
_11
.bundles('BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({status: 'pending-review'})
_11
.then(bundle => console.log(bundle.sid));

Output

_18
{
_18
"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"regulation_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"friendly_name": "friendly_name",
_18
"status": "pending-review",
_18
"email": "email",
_18
"status_callback": "http://www.example.com",
_18
"valid_until": null,
_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/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"links": {
_18
"evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",
_18
"item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ItemAssignments",
_18
"bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Copies"
_18
}
_18
}


Rate this page: