SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site,, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

How do I upload and Map an Identity Document?

Some Twilio phone numbers may require a verified identity document due to local regulations. If a phone number requires an identity document to be on file prior to purchasing, you will see a message in Console or an error message from the API (Error 21650) pointing you to the Console page where you can upload the required documentation. Please continue reading for instructions on uploading an identity document for your Twilio project.


Create a new Identity Document

  1. Login to your project at
  2. Navigate to Phone Numbers > Documents.
  3. Click Add new Identity Document, or the red Plus sign icon.

From this page, you will have to provide the name of the individual and/or entity registering the phone numbers, certain details about the individual or entity as required in the form, and a scanned copy of supporting identification documents. Please note that the supporting identification documents must contain the same information as the required details. For example, if the required details specify an address, then your supporting documentation must also include an address. Selecting the type of number you intend to purchase will show which fields are mandatory (*) and optional.


Upon submission, the identity document record will be in Pending state until Twilio verifies the documents, which usually occurs within 48 business hours. When approved, the identity document record will transition to a Passed state.


Once passed verification, the Identity Document can be used to purchase the number:


Can I create identity documents via API?

Initially, uploading of identity documents is only be possible via Console. We plan to release an update that will allow creating identities and getting verification status callbacks via the Twilio REST API in the near future.

Map existing numbers to an Identity Document

If you have existing numbers on your Twilio project that were purchased prior to these new ID requirements, they will need to be mapped to the appropriate address and identity documents. Follow the instructions below to map your existing numbers.

  1. Login to your project at
  2. Navigate to Phone Numbers > Manage Numbers.
  3. Click the desired phone number to map.
  4. Under the Regulatory Information section, select the Address and/or Identity Document you wish to use, and then click Save.

Please note that if an Address or previously uploaded Identity Document does not appear in the drop-down menu, this means it may not have passed verification, or that it doesn’t satisfy the regulatory requirement (i.e. either the Address is in the wrong locality or the Identity Document has missing information). For more information, please see the article on Identity Verification.

When you have successfully mapped your address and phone number, you'll see a "compliant" notice next the address dropdown under the Regulatory Information: 


German Local Address Requirement

In addition to identity documents, German local numbers also require an address in the same locality as the prefix of the number. Addresses can be added via Console, or the REST API. For more information, please see our article How do I update my address.

Have more questions? Submit a request
Powered by Zendesk