Important Change to the IncomingPhoneNumbers Provisioning API

Important Change to the IncomingPhoneNumbers Provisioning API

At Twilio, it’s important for us to share when there are changes to phone numbers that may affect you. This change is relevant to anyone who provisions regulated phone numbers via the IncomingPhoneNumbers provisioning API.

On February 12, 2020, when you provision new phone numbers through the /IncomingPhoneNumbers API, you will be required to include the proper documentation for regulated phone numbers. API calls to provision phone numbers that do not include a valid BundleSID / IdentitySID will fail with error code 21649. We will send you multiple communications to prepare you for this change. If you are using Console, this will not result in a change.

Additionally, there will be a brownout on January 15, 2020, during which the BundleSID / IdentitySID parameter will be changed from optional to mandatory for the IncomingPhoneNumbers API to ensure all of our customers are prepared for the February 12, 2020 change.

Frequently asked questions about this change

In this blog post, we want to address questions we’re seeing around the change.

How do I know if this change impacts me?

If you provision phone numbers in regulated geographies via the IncomingPhoneNumbers API, this will impact you when you provision new phone numbers. You can learn more about geography regulations here.

What do I need to do?

Begin building documentation bundles for your phone numbers.  Every regulated geography and affiliated number type where you provision phone numbers will require a bundle. So, if you primarily provision German toll-free numbers through the API, it is critical that you build a German toll-free bundle.

Is this change driven by regulatory compliance?

We are making this change due to the increasing importance of regulatory compliance for phone numbers across the world.  Many countries have recently been increasing their scrutiny of how their phone numbers are used. This increased scrutiny is driven by various factors, including increased incidents of misuse and abuse of phone numbers, heightened national security concerns, and increased pressure on the supply of numbers. As a result, various countries are updating their regulations or placing greater emphasis on the enforcement of existing regulations, including those requiring validation of who is actually using the phone number and exactly where that individual or business is located.

Essentially the purpose of these regulations is to verify who is using a number and where they are located. Twilio, our customers, end-users, and providers each have a role and a collective obligation to ensure numbers are assigned and used in a manner consistent with the intent of the regulations in the relevant country.

Why is Twilio making this change?

We decided to make this change with our customers’ best interests at heart as we monitor the regulatory compliance landscape. Twilio, our customers, end-users, and providers each have a role and a collective obligation to ensure numbers are assigned and used in a manner consistent with the intent of the regulations in the relevant country. Our goal is to avoid any of our customers being in jeopardy of losing a phone number due to noncompliance with phone number regulations.

We understand that this change may be inconvenient and frustrating. Our goal is to protect your phone numbers within days of provisioning them by collecting the necessary information upfront through the API instead of asking our customers to react in a short timeframe when a number is out of compliance.

Why is there a brownout on January 15?

We know that most people receive a huge number of emails every day. While we are sending emails to customers that we expect will be impacted by this change (and publishing this blog post), that doesn’t mean that everyone who needs to know about this change will read this blog post or the emails we send. By having a brownout on January 15 between 6:00 and 9:00 a.m. Pacific Time (PT), our goal is to make sure all of our customers are aware of this change and then have around one month to prepare for the February 12, 2020 change.

Is there a way to report which phone numbers are missing Regulatory Bundles?

To determine which phone numbers are missing Regulatory Bundles, please use the Compliance Report in Twilio’s web Console. For information on how to use the Compliance Report, please refer to the Getting Started page.

If I don’t use the API, does this impact Console?

For regulated countries that require identity information and documentation, you are already required to provide this information in Console.

What happens if I make an API call to provision a phone number and I do not include a valid BundleSID / IdentitySID?

If you try to provision a phone number in a regulated country and the API call does not include a valid BundleSID / IdentitySID, the API call will fail with error code 21649.

What will happen if I try to provision a phone number via the API for a country that only requires an address?

For Number Groups with name and address only requirements, you will not experience a change. In future versions, Regulatory Bundles will require Addresses to be assigned, even if there is no proof required.

What will happen if I try to provision a phone number via the API for a country that requires address and name, but no proof of address or identity?

Same as above! For Number Groups with name and address only requirements, you will not experience a change. In future versions, Regulatory Bundles will require Addresses to be assigned, even if there is no proof required.

What will happen if I try to provision a phone number via the API for a country that requires name, address and proof of address (but no proof of identity)?

All phone numbers that require proof will require a Regulatory Bundle included in the number requested to be provisioned starting on February 12, 2020.

What should I do if I still have questions?

We’re happy to help you with this change. If you can’t find the information you need, please reach out to support through the site or at help@twilio.com.