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.
Expand image
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 EndUserType
type: enum<string>
The type of End User the regulation requires - can be individual
or business
.
Possible values:
individual
business
IsoCountry
type: string
The ISO country code of the phone number's country.
NumberType
type: string
The type of phone number that the regulatory requiremnt is restricting.
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_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 client.numbers.v2.regulatoryCompliance
_16 endUserType: 'individual',
_16 .then(regulations => regulations.forEach(r => console.log(r.sid)));
_74 "sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_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",
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 FriendlyName
type: string Required
The string that you assigned to describe the resource.
Email
type: string Required
The email address that will receive updates when the Bundle resource changes status.
StatusCallback
type: string<uri>
The URL we call to inform your application of status changes.
RegulationSid
type: SID<RN>
The unique string of a regulation that is associated to the Bundle resource.
Pattern:
^RN[0-9a-fA-F]{32}$
EndUserType
type: enum<string>
NumberType
type: string
The type of phone number of the Bundle's ownership request. Can be local
, mobile
, national
, or toll free
.
_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 client.numbers.v2.regulatoryCompliance
_18 endUserType: 'business',
_18 statusCallback: 'https://my.status.callback.com',
_18 friendlyName: 'Twilio GmbH',
_18 email: 'numbers-regulatory-review@twilio.com'
_18 .then(bundle => console.log(bundle.sid));
_18 "sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "regulation_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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"
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 FriendlyName
type: string Required
The string that you assigned to describe the resource.
Type
type: enum<string> Required
The type of end user of the Bundle resource - can be individual
or business
.
Possible values:
individual
business
Attributes
type: object
The set of parameters that are the attributes of the End User resource which are derived End User Types.
_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 client.numbers.v2.regulatoryCompliance
_13 .create({attributes: {
_13 business_name: 'Twilio'
_13 }, friendlyName: 'Twilio GmbH', type: 'business'})
_13 .then(end_user => console.log(end_user.sid));
_12 "sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12 "friendly_name": "Twilio GmbH",
_12 "business_name": "Twilio"
_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"
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 FriendlyName
type: string Required
The string that you assigned to describe the resource.
Type
type: string Required
The type of the Supporting Document.
Attributes
type: object
The set of parameters that are the attributes of the Supporting Documents resource which are derived Supporting Document Types.
_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 client.numbers.v2.regulatoryCompliance
_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));
_18 "sid": "RDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "friendly_name": "TwilioBusinessRegistration",
_18 "mime_type": "mime_type",
_18 "failure_reason": null,
_18 "type": "business_registration",
_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 "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"
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
.
URI parameters BundleSid
type: SID<BU>
The unique string that we created to identify the Bundle resource.
Pattern:
^BU[0-9a-fA-F]{32}$
Request body parameters ObjectSid
type: SID Required
The SID of an object bag that holds information of the different items.
Pattern:
^[a-zA-Z]{2}[0-9a-fA-F]{32}$
_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 client.numbers.v2.regulatoryCompliance
_12 .bundles('BUe6c04e6a1a6133a9d3d2314e38f51dfb')
_12 .create({objectSid: 'RD70f07ace005177cbfee907bc9c1acabd'})
_12 .then(item_assignment => console.log(item_assignment.bundleSid));
_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"
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 Sid
type: SID<BU>
The unique string that we created to identify the Bundle resource.
Pattern:
^BU[0-9a-fA-F]{32}$
Request body parameters Status
type: enum<string>
The verification status of the Bundle resource.
Possible values:
draft
pending-review
in-review
twilio-rejected
twilio-approved
provisionally-approved
StatusCallback
type: string<uri>
The URL we call to inform your application of status changes.
FriendlyName
type: string
The string that you assigned to describe the resource.
Email
type: string
The email address that will receive updates when the Bundle resource changes status.
_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 client.numbers.v2.regulatoryCompliance
_11 .bundles('BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .update({status: 'pending-review'})
_11 .then(bundle => console.log(bundle.sid));
_18 "sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "regulation_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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"