Menu

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?

REST API: Addresses

An Address instance resource represents your or your customer’s physical location within a country. Around the world, some local authorities require the name and address of the user to be on file with Twilio to purchase and own a phone number. Address requirements are exposed as a property on the AvailablePhoneNumber resource.

Addresses contain the name of your company or your customer’s company in addition to location information and an optional friendly name. Each Address created on an account or subaccount can be used for any phone numbers purchased on that account. After creating an address, it can be used to satisfy the requirements for multiple phone numbers and phone numbers with address requirements can be purchased using the IncomingPhoneNumber resource.

In some countries, to comply with local regulation, addresses are validated to ensure the integrity and accuracy of the data provided. In those countries, if the address you provide does not pass validation, it is not accepted as an Address and error code 21628 is returned. If the address submitted is not an exact match but is similar to a valid address, we’ll create the Address using the valid address we found, unless you include the AutoCorrectAddress=false parameter in the request. In that case, we’ll provide it as a suggested address in error code 21629. If the suggested address is indeed the address of your company or your customer’s company, then use the suggested format to create a valid Address.

The Address list resource represents all of the Addresses that you have created on your account within Twilio. You can POST to Addresses to create a new address or modify an existing address.

Address properties

account_sid
sid<AC> Not PII

The unique id of the Account responsible for this address.

city
string Not PII

The city in which you or your customer is located.

customer_name

Your name or business name, or that of your customer.

emergency_enabled
boolean Not PII

This is a value that indicates if emergency calling has been enabled on this number. Possible values are true or false.

friendly_name

A human-readable description of the address. Maximum 64 characters.

iso_country
iso_country_code Not PII

The ISO country code of your or your customer's address.

postal_code

The postal code in which you or your customer is located.

region
string Not PII

The state or region in which you or your customer is located.

sid
sid<AD> Not PII

A 34 character string that uniquely identifies this address.

street

The number and street address where you or your customer is located.

uri
uri Not PII

The URI for this resource, relative to https://api.twilio.com.

validated
boolean Not PII

In some countries, addresses are validated to comply with local regulation. In those countries, if the address you provide does not pass validation, it will not be accepted as an Address. This value will be true if the Address has been validated, or false for countries that don't require validation or if the Address is non-compliant.

Create an Address resource

post
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses.json

Creates a new Address within your account.

Parameters
City
Required
post string Not PII

The city in which you or your customer is located.

CustomerName
Required
post string PII MTL: 30 DAYS

Your name or business name, or that of your customer.

IsoCountry
Required
post iso_country_code Not PII

The ISO country code of your or your customer's address.

PostalCode
Required
post string PII MTL: 30 DAYS

The postal code in which you or your customer is located.

Region
Required
post string Not PII

The state or region in which you or your customer is located.

Street
Required
post string PII MTL: 30 DAYS

The number and street address where you or your customer is located.

AutoCorrectAddress
Optional
post boolean Not PII

If you don't set a value for this parameter, or if you set it to true, then the system will, if necessary, auto-correct the address you provide. If you don't want the system to auto-correct the address, you will explicitly need to set this value to false.

FriendlyName
Optional
post string PII MTL: 30 DAYS

A human-readable description of the new address. Maximum 64 characters.

Example 1
Loading Code Sample...
      
      
      
      

      If successful, Twilio will respond with a representation of the new address.

      Address Validation Related Errors

      Error Code Error Name Error Description
      21615 Phone Number Requires a Local Address To purchase this number you must have an Address on your account which satisfies the local address requirements.
      21628 Address Validation Error The address you have provided cannot be validated.
      21629 Address Validation Error - Check Suggested Address The address you have provided cannot be validated. A similar address has been found to be valid. The suggested address is included in the error message body.

      Fetch an Address resource

      get
      https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{Sid}.json
      Example 1
      Loading Code Sample...
          
          
          
          

          Read multiple Address resources

          get
          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses.json

          Returns a list of Address resource representations, each representing an address within your account. The list includes [paging information][paging-info].

          Parameters
          CustomerName
          Optional
          get string PII MTL: 30 DAYS

          Only return the Address resources with customer names that exactly match this name.

          FriendlyName
          Optional
          get string PII MTL: 30 DAYS

          Only return the Address resources with friendly names that exactly match this name.

          IsoCountry
          Optional
          get iso_country_code Not PII

          Only return the Address resources in this country.

          Example 1
          Loading Code Sample...
              
              
              
              
              Example 2
              Loading Code Sample...
                  
                  
                  
                  
                  Example 3
                  Loading Code Sample...
                      
                      
                      
                      
                      Show all phone numbers on your account that require the address `AD2a0747eba6abf96b7e3c3ff0b4530f6e`

                      List Dependent PNS Subresources

                      Show all phone numbers on your account that require the address `AD2a0747eba6abf96b7e3c3ff0b4530f6e`
                      GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{AddressSid}/DependentPhoneNumbers.json
                      

                      Returns a list of IncomingPhoneNumbers on your account that require the specified address.

                      Dependent Phone Numbers Instance Subresource

                      Each Address instance resource supports a subresource for viewing which phone numbers are dependent on your existing addresses. In the case that you have two addresses which satisfy the requirement on a given phone number, this subresource will not return the phone number in the list.

                      Paging

                      The list includes paging information. If you plan on requesting more records than will fit on a single page, you should use the provided nextpageuri rather than incrementing through the pages by page number. Using the nextpageuri helps to ensure that your next request picks up where it left off and can prevent you from retrieving duplicate data if you are actively creating addresses.

                      Update an Address resource

                      post
                      https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{Sid}.json

                      A POST request attempts to update an individual Address instance and returns the updated resource representation if successful. A successful returned response is identical to that of the HTTP GET.

                      Note that that all fields but IsoCountry can be updated using a POST request. To update the IsoCountry, a new Address must be created.

                      Parameters
                      AutoCorrectAddress
                      Optional
                      post boolean Not PII

                      If you don't set a value for this parameter, or if you set it to true, then the system will, if necessary, auto-correct the address you provide. If you don't want the system to auto-correct the address, you will explicitly need to set this value to false.

                      City
                      Optional
                      post string Not PII

                      The city in which you or your customer is located.

                      CustomerName
                      Optional
                      post string PII MTL: 30 DAYS

                      Your name or business name, or that of your customer.

                      FriendlyName
                      Optional
                      post string PII MTL: 30 DAYS

                      A human-readable description of the address. Maximum 64 characters.

                      PostalCode
                      Optional
                      post string PII MTL: 30 DAYS

                      The postal code in which you or your customer is located.

                      Region
                      Optional
                      post string Not PII

                      The state or region in which you or your customer is located.

                      Street
                      Optional
                      post string PII MTL: 30 DAYS

                      The number and street address where you or your customer is located.

                      Example 1
                      Loading Code Sample...
                          
                          
                          
                          
                          Update the customer name and street to ‘Customer 456’ and ‘2 Hasselhoff Lane’.

                          Update a customer name and street address

                          Update the customer name and street to ‘Customer 456’ and ‘2 Hasselhoff Lane’.

                          Delete an Address resource

                          delete
                          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{Sid}.json

                          Deletes this address from your account.

                          If this address is required for any active IncomingPhoneNumbers, it cannot be deleted and you will receive Error [21625][21625]. However, if you have a second address that fulfills the AddressRequirement, the address will be successfully deleted. The DependentPhoneNumbers Instance Subresource will allow you to see which IncomingPhoneNumbers require a given address.

                          If the delete is successful, Twilio will return an HTTP 204 response with no body.

                          Example 1
                          Loading Code Sample...
                              
                              
                              
                              

                              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.

                              Loading Code Sample...