Menu

Expand
Rate this page:

Thanks for rating this page!

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

Voice Dialing Permissions REST API

Twilio allows you to initiate outbound voice calls to the public telephone network in over 218 countries and territories around the world. Account level Voice Dialing Geographic Permissions allows you to control which of those countries can be called and also block destinations in countries with a high-risk of toll fraud.

For our partners that build and re-sell Twilio powered solutions using subaccounts, Twilio has provided the ability for a subaccount to inherit the dialing permissions of the Master Project. If the partner's customer (the tenant of the subaccount) requires a unique set of permissions, inheritance can be disabled and dialing permissions can be customized on that subaccount.

With this REST API for voice dialing permissions, you can create smart defaults for customers during signup. Smart defaults, aligned with customer needs, leads to more successful calls and more conversions.

Country permissions

Voice dialing permissions are organized into country permissions identified by ISO code of corresponding country.

For every Voice Dialing Country Permission resource, there are three different groups of phone number prefixes.
The following properties can be used to enable each group:

NAME DESCRIPTION
high_risk_special_numbers_enabled

true if dialing to high-risk special services numbers is enabled, else false. This group of prefixes are number ranges allocated by the corresponding country. They consist of number types such as premium numbers, special services, shared cost, and others (not PII)

high_risk_tollfraud_numbers_enabled

true if dialing to high-risk toll fraud numbers is enabled, else false. This group of prefixes are narrow number ranges that have a high-risk of international revenue sharing fraud (IRSF) attacks also called toll fraud. The group of prefixes is formed through integration with anti-fraud databases and verified by analyzing calls on the Twilio Super Network. This group of prefixes are not available for download and are updated frequently (not PII)

low_risk_numbers_enabled

true if low risk numbers are enabled, else false (not PII)

The following are a set of actions that can be performed on the country permissions in an account.


Fetch all Country permissions

To fetch all country permissions on an account, you must make an HTTP GET request to the Voice Dialing Country Permissions resource.

GET https://voice.twilio.com/v1/DialingPermissions/Countries
        
        
        
        

        The following are optional query filters for the list of country permissions. Note, parameters are case-sensitive.

        Names in PHP format
        isoCode
        Required
        get iso_country_code Not PII

        The ISO country code

        The following are the country permissions resource properties.

        Names in PHP format
        isoCode
        iso_country_code Not PII

        The ISO country code.

        name
        string Not PII

        Name of the country

        continent
        string Not PII

        Name of the continent

        countryCodes
        string[] Not PII

        The E.164 assigned country codes(s)

        lowRiskNumbersEnabled
        boolean Not PII

        true, if dialing to low-risk numbers is enabled, else false.

        highRiskSpecialNumbersEnabled
        boolean Not PII

        true, if dialing to high-risk special services numbers is enabled, else false. This group of prefixes includes number ranges allocated by the corresponding country. They consist of number types such as premium numbers, special services, shared cost and others

        highRiskTollfraudNumbersEnabled
        boolean Not PII

        true, if dialing to high-risk toll fraud numbers is enabled, else false. This group of prefixes includes narrow number ranges that have a high-risk of international revenue sharing fraud (IRSF) attacks also called toll fraud. The group of prefixes is formed through integration with anti-fraud databases and verified by analyzing calls on the Twilio Super Network. This group of prefixes is not available for download and is updated frequently

        url
        url Not PII

        The absolute URL of this resource.

        links
        uri_map Not PII

        A list of URLs related to this resource.

        Fetch Country permissions by ISO code

        You can fetch the permissions for a single country by specifying the IsoCode in the HTTP GET request.

        GET https://voice.twilio.com/v1/DialingPermissions/Countries/{IsoCode}
        
              
              
              
              

              The following is how to fetch country permissions by ISO code.

              Names in PHP format
              isoCode
              Required
              get iso_country_code Not PII

              The ISO country code

              The following are the country permissions resource properties.

              Names in PHP format
              isoCode
              iso_country_code Not PII

              The ISO country code.

              name
              string Not PII

              Name of the country

              continent
              string Not PII

              Name of the continent

              countryCodes
              string[] Not PII

              The E.164 assigned country codes(s)

              lowRiskNumbersEnabled
              boolean Not PII

              true, if dialing to low-risk numbers is enabled, else false.

              highRiskSpecialNumbersEnabled
              boolean Not PII

              true, if dialing to high-risk special services numbers is enabled, else false. This group of prefixes includes number ranges allocated by the corresponding country. They consist of number types such as premium numbers, special services, shared cost and others

              highRiskTollfraudNumbersEnabled
              boolean Not PII

              true, if dialing to high-risk toll fraud numbers is enabled, else false. This group of prefixes includes narrow number ranges that have a high-risk of international revenue sharing fraud (IRSF) attacks also called toll fraud. The group of prefixes is formed through integration with anti-fraud databases and verified by analyzing calls on the Twilio Super Network. This group of prefixes is not available for download and is updated frequently

              url
              url Not PII

              The absolute URL of this resource.

              links
              uri_map Not PII

              A list of URLs related to this resource.

              Bulk Update Country permissions

              To update country permissions in bulk, you must make a HTTP POST request to the BulkCountryUpdates resource.

              POST https://voice.twilio.com/v1/DialingPermissions/Countries/BulkCountryUpdates
              

              This endpoint requires a JSON list of objects passed as URL encoded FORM parameter using the application/x-www-form-urlencoded content type.

              Example country permissions update

              To update country permissions for iso_code = GB, the following is a sample UpdateRequest object

              [{
                  "high_risk_special_numbers_enabled": true,
                  "low_risk_numbers_enabled": true,
                  "high_risk_tollfraud_numbers_enabled": false,
                  "iso_code": "GB"
              }]
              

              Here's a cURL request the above UpdateRequest with -F curl flag

              curl -X POST https://voice.twilio.com/v1/DialingPermissions/BulkCountryUpdates \
              -F 'UpdateRequest=[ { "iso_code" : "US", "low_risk_numbers_enabled" : "true", "high_risk_special_numbers_enabled" : "false", "high_risk_tollfraud_numbers_enabled" : "false" } ]'\
              -u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token
              

              Here's a cURL request with URL encoded FORM parameter using the above UpdateRequest

              curl -X POST \
                https://voice.twilio.com/v1/DialingPermissions/BulkCountryUpdates \
              -u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token \
                -H 'content-type: application/x-www-form-urlencoded' \
                -d UpdateRequest=%5B%7B%0A%20%20%20%20%22high_risk_special_numbers_enabled%22%3A%20true%2C%0A%20%20%20%20%22low_risk_numbers_enabled%22%3A%20true%2C%0A%20%20%20%20%22high_risk_tollfraud_numbers_enabled%22%3A%20false%2C%0A%20%20%20%20%22iso_code%22%3A%20%22US%22%0A%7D%5D
              
                    
                    
                    
                    
                    Update and enable voice dialing to all number groups for the country United States with ISO code [US]

                    Update voice dialing country permissions for US

                    Update and enable voice dialing to all number groups for the country United States with ISO code [US]
                          
                          
                          
                          
                          Enable low risk number groups' voice dialing permissions on the list of countries with ISO codes [ US , DE , FR , GB , IL , IN , JP , AU , BR]

                          Enable Voice dialing for low risk numbers on a given set of countries

                          Enable low risk number groups' voice dialing permissions on the list of countries with ISO codes [ US , DE , FR , GB , IL , IN , JP , AU , BR]
                                
                                
                                
                                
                                Disable the following high-risk countries with ISO codes [ CU , LV , SO , LT , GN , GM , ZW , MV , TN, EE]

                                Disable Voice dialing for high risk numbers in a given set of highest risk countries

                                Disable the following high-risk countries with ISO codes [ CU , LV , SO , LT , GN , GM , ZW , MV , TN, EE]

                                The following are the required form parameters for making a bulk update POST request.

                                Names in PHP format
                                updateRequest
                                Required
                                post string Not PII

                                URL encoded JSON array of update objects. example : [ { "iso_code": "GB", "low_risk_numbers_enabled": "true", "high_risk_special_numbers_enabled":"true", "high_risk_tollfraud_numbers_enabled": "false" } ]

                                The form parameter UpdateRequest is a URL encoded JSON list of objects with the following properties:

                                NAME DESCRIPTION
                                iso_code

                                The ISO country code (not PII)

                                high_risk_special_numbers_enabled

                                true if high-risk special numbers are enabled, else false (not PII)

                                high_risk_tollfraud_numbers_enabled

                                true if high-risk toll fraud numbers are enabled, else false (not PII)

                                low_risk_numbers_enabled

                                true if low risk numbers are enabled, else false (not PII)

                                Here are the response object properties for the above POST request:

                                NAME DESCRIPTION
                                update_count

                                Integer: The number of countries updated (not PII)

                                update_request

                                String: Success, when request is successful or else, Error(not PII)

                                Fetch all high-risk prefixes from a country permission resource

                                To fetch all high-risk prefixes from a country you must make a HTTP GET request to the Voice Dialing Country Permissions high-risk special prefixes resource:

                                GET https://voice.twilio.com/v1/DialingPermissions/Countries/{IsoCode}/HighRiskSpecialPrefixes
                                
                                      
                                      
                                      
                                      

                                      The following is a required path parameter.

                                      Names in PHP format
                                      isoCode
                                      Required
                                      get iso_country_code Not PII

                                      The ISO 3166-1 country code to identify the country permissions from which high-risk special service number prefixes are fetched

                                      Here are the properties of the prefixes response object:

                                      Names in PHP format
                                      prefix
                                      string Not PII

                                      A prefix is a contiguous number range for a block of E.164 numbers that includes the E.164 assigned country code. For example, a North American Numbering Plan prefix like +1510720 written like +1(510) 720 matches all numbers inclusive from +1(510) 720-0000 to +1(510) 720-9999.

                                      Fetch Inheritance Settings of Voice Dialing Permissions

                                      You can fetch the inheritance settings of a subaccount for voice dialing permissions using the HTTP GET request.

                                      GET https://voice.twilio.com/v1/Settings
                                      

                                            
                                            
                                            
                                            
                                            Request to fetch the inheritance of voice dialing permissions for a sub-account

                                            Fetch Inheritance Settings of Voice Dialing Permissions for a sub-account

                                            Request to fetch the inheritance of voice dialing permissions for a sub-account

                                            Here are the properties of the response object:

                                            Names in PHP format
                                            dialingPermissionsInheritance
                                            boolean Not PII

                                            true if this sub-account will inherit voice dialing permissions from the Master Project; otherwise false.

                                            url
                                            url Not PII

                                            The absolute URL of this resource.

                                            Update Inheritance Settings of Voice Dialing Permissions

                                            You can update the inheritance settings of a subaccount for voice dialing permissions using the HTTP POST request.

                                            POST https://voice.twilio.com/v1/Settings
                                            
                                                  
                                                  
                                                  
                                                  
                                                  Request to update the inheritance of voice dialing permissions for a sub-account

                                                  Update Inheritance Settings of Voice Dialing Permissions for a sub-account

                                                  Request to update the inheritance of voice dialing permissions for a sub-account

                                                  The following is a required parameter.

                                                  Names in PHP format
                                                  dialingPermissionsInheritance
                                                  Optional
                                                  post boolean Not PII

                                                  true for this sub-account to inherit voice dialing permissions from the Master Project; otherwise false.

                                                  Here are the properties of the response object:

                                                  Names in PHP format
                                                  dialingPermissionsInheritance
                                                  boolean Not PII

                                                  true if this sub-account will inherit voice dialing permissions from the Master Project; otherwise false.

                                                  url
                                                  url Not PII

                                                  The absolute URL of this resource.

                                                  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.