Regulatory requirements in some countries mandate that Twilio collect information about the phone number’s end-user before we can allocate a number. When we are required to collect the end-user’s address, we may, depending on the country that the address is in, validate the address with an external provider. If you’re creating a new address in one of those countries via Console, you may get an address suggestion when we find a close match, while via API you may get an address suggestion in the error response.
Notice: If you are having trouble adding an address that requires a proof of documentation for regulatory requirements, ensure you are adding the address within the bundle creation process using this process: How to Submit a Regulatory Bundle for Phone Number Regulatory Compliance
Table of Contents
- Why is address validation important?
- In what countries does Twilio validate addresses?
- What does “validated” mean in Console?
- Do all types of numbers require an address validated by Twilio’s system?
- How do I validate an existing address?
- What can I do if my address is not being successfully validated?
- How do I map an address to a number I already own?
Why is address validation important?
Regulators and operators may request Twilio’s end-user data at any time. If the data request is lawfully executed, Twilio must comply and provide an audit report of its in-use numbers. In some countries, end-user data must be held by the underlying operator or the regulatory agency in the country. To ensure we have valid address data linked to each phone number, we use a third-party address validation service.
In what countries does Twilio validate addresses?
For Regulatory Requirements we currently enforce address validation for addresses in: Australia, Brazil, France, Germany, Ireland, Italy, Mexico, the Netherlands, Poland, Spain, Luxembourg, Austria, and United Kingdom.
United States and Canada addresses may be emergency validated for Emergency Calling purposes.
Notice: For United States addresses enter the "State" using the state abbreviation. The "State" field will only accept states formatted in two-letter abbreviations, e.g., TX, NY, CA. If written out ('Texas', 'New York', 'California') the address will be rejected.
What does “validated” mean in Console?
On the Addresses page and in the Address detail page in Console, you’ll find a “Validated” field associated with each address on your account. If an address has never been validated or has failed validation, this field will show “No”. If the address has been successfully validated, the field will display “Yes”.
Do all types of numbers require an address validated by Twilio’s system?
No, but every address must be a valid address (i.e., an address that actually exists). Here’s the difference. We only enforce that a system-validated address is used for purchase of numbers that have a Local Address requirement. The Local Address requirement is an address in the same country or locality (depending on the country and type of number) as the number being purchased. All addresses used to purchase numbers with a Local Address requirement must first be validated by our system. If, however, you are purchasing a number that has an Any Address requirement (i.e. anywhere in the world), then you can use any address on your account, even if it is not system-validated. This is due to the fact that we do not enforce address validation globally at this time.
How do I validate an existing address?
When we enable address validation in a new country, we back-validate all existing addresses in our database for that country and mark them validated if we find an exact match (i.e., there will be a “Yes” next to the phone number in the validated field). If we find a partial match (which would require the user’s acceptance of a suggested address), we mark the address with a “No” in the validated field of the phone number. If you have an address in your account that is marked not validated and need to use it to purchase a number that requires a validated address, you can manually run the validation process by clicking the “Validate” button on the Addresses page or in the Address detail page in Console.
Alternatively, to revalidate the address via API, make a POST request to the Address instance endpoint along with the all the address fields. If the address is not previously validated, Twilio will revalidate the address and you may get an address suggestion in the error response.
What can I do if my address is not being successfully validated?
Address validation services are not perfect and sometimes valid addresses aren’t found or are in the incorrect format. If that happens, please try alternative formats of your address.
Some best practices are to:
All fields
- Be sure NOT to add any extra spaces before or after any of the information enter in each field.
Customer Name, Friendly Name
- Remove special characters and symbols like "&", "@", "#".
Street
- Use abbreviations where possible, i.e., "St" for Street, "Ave" for Avenue, "Bl" for Boulevard, etc.
- Do NOT use punctuation with the abbreviation.
- Remove special characters and symbols like "&", "@", "#".
Locality
- Remove special characters and symbols like "&", "@", "#".
Region
- Use the two-letter abbreviation for the State field, i.e., "CA" for California.
- Use capital letters and no punctuation.
Postal Code
- Use the standard 5-digit ZIP Code, not the 5+4 format.
If you’re still having problems validating your address, please contact our Support team.
How do I map an address to a number I already own?
You may have purchased certain phone numbers before we implemented new address requirements pertaining to those numbers. If so, there is no address associated with, or “mapped” to, your previously-purchased phone numbers. You should map these numbers to an appropriate address to ensure that we have the correct information on hand if there is ever a regulatory inquiry. To map an address to a phone number, follow the instructions below:
- Access the Active Numbers page in Console.
- Click the desired phone number for mapping your address.
- Click the Regulatory Information tab.
- Select the Address you wish to use from the drop-down menu, and then click Save.
Notice: If a previously entered address does not appear in the drop-down menu, it may not have passed validation, or it may not satisfy the regulatory requirement (i.e. the Address is in the wrong locality).
Alternatively, to map an address via API, see the Incoming Phone Numbers API documentation for details on how to use the AddressSid parameter.