Menu

Expand
Rate this page:

Getting Started: Regulatory Compliance Public REST APIs

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

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

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 .

Parameters in REST API format
end_user_type
Optional
get ienum:end_user_type Not PII

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

iso_country
Optional
get string Not PII

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

number_type
Optional
get string Not PII

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

        
        
        
        

        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.

        Parameters in REST API format
        friendly_name
        Required
        post string Not PII

        The string that you assigned to describe the resource.

        email
        Required
        post string Not PII

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

        status_callback
        Optional
        post url Not PII

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

        regulation_sid
        Optional
        post sid<RN> Not PII

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

        iso_country
        Optional
        post string Not PII

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

        end_user_type
        Optional
        post ienum:end_user_type Not PII

        The type of End User of the Bundle resource.

        number_type
        Optional
        post string Not PII

        The type of phone number of the Bundle's ownership request.

              
              
              
              

              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.

              Parameters in REST API format
              friendly_name
              Required
              post string Not PII

              The string that you assigned to describe the resource.

              type
              Required
              post ienum:type Not PII

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

              attributes
              Optional
              post object 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 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.

                    Parameters in REST API format
                    friendly_name
                    Required
                    post string Not PII

                    The string that you assigned to describe the resource.

                    type
                    Required
                    post string Not PII

                    The type of the Supporting Document.

                    attributes
                    Optional
                    post object 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 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 ---date-urlencode to -F as shown in the example.

                                
                                
                                
                                

                                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.

                                Parameters in REST API format
                                bundle_sid
                                Path
                                post sid<BU> Not PII

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

                                object_sid
                                Required
                                post sid Not PII

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

                                      
                                      
                                      
                                      

                                      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.

                                      Parameters in REST API format
                                      sid
                                      Path
                                      post sid<BU> Not PII

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

                                      status
                                      Optional
                                      post ienum:status Not PII

                                      The verification status of the Bundle resource.

                                      status_callback
                                      Optional
                                      post url Not PII

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

                                      friendly_name
                                      Optional
                                      post string Not PII

                                      The string that you assigned to describe the resource.

                                      email
                                      Optional
                                      post string Not PII

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

                                            
                                            
                                            
                                            
                                            Rate this page:

                                            Need some help?

                                            We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                                                  
                                                  
                                                  

                                                  Thank you for your feedback!

                                                  We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                                  Sending your feedback...
                                                  🎉 Thank you for your feedback!
                                                  Something went wrong. Please try again.

                                                  Thanks for your feedback!

                                                  Refer us and get $10 in 3 simple steps!

                                                  Step 1

                                                  Get link

                                                  Get a free personal referral link here

                                                  Step 2

                                                  Give $10

                                                  Your user signs up and upgrade using link

                                                  Step 3

                                                  Get $10

                                                  1,250 free SMSes
                                                  OR 1,000 free voice mins
                                                  OR 12,000 chats
                                                  OR more