Menu

Expand
Rate this page:

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

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that is responsible for the Address resource.

city
string Not PII

The city in which the address is located.

customer_name

The name associated with the address.This property has a maximum length of 16 4-byte characters, or 21 3-byte characters.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

friendly_name

The string that you assigned to describe the resource.

iso_country
iso_country_code Not PII

The ISO country code of the address.

postal_code

The postal code of the address.

region
string Not PII

The state or region of the address.

sid
sid<AD> Not PII

The unique string that that we created to identify the Address resource.

street

The number and street address of the address.

uri
uri Not PII

The URI of the resource, relative to https://api.twilio.com.

emergency_enabled
boolean Not PII

Whether emergency calling has been enabled on this number.

validated
boolean Not PII

Whether the address has been validated to comply with local regulation. In countries that require valid addresses, an invalid address will not be accepted. true indicates the Address has been validated. false indicate the country doesn't require validation or the Address is not valid.

verified
boolean Not PII

Whether the address has been verified to comply with regulation. In countries that require valid addresses, an invalid address will not be accepted. true indicates the Address has been verified. false indicate the country doesn't require verified or the Address is not valid.

street_secondary

The additional number and street address of the address.

Create an Address resource

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

Creates a new Address within your account.

Parameters
Parameters in REST API format
account_sid
Path
post sid<AC> Not PII

The SID of the Account that will be responsible for the new Address resource.

customer_name
Required
post string PII MTL: 30 DAYS

The name to associate with the new address.

street
Required
post string PII MTL: 30 DAYS

The number and street address of the new address.

city
Required
post string Not PII

The city of the new address.

region
Required
post string Not PII

The state or region of the new address.

postal_code
Required
post string PII MTL: 30 DAYS

The postal code of the new address.

iso_country
Required
post iso_country_code Not PII

The ISO country code of the new address.

friendly_name
Optional
post string PII MTL: 30 DAYS

A descriptive string that you create to describe the new address. It can be up to 64 characters long.

emergency_enabled
Optional
post boolean Not PII

Whether to enable emergency calling on the new address. Can be: true or false.

auto_correct_address
Optional
post boolean Not PII

Whether we should automatically correct the address. Can be: true or false and the default is true. If empty or true, we will correct the address you provide if necessary. If false, we won't alter the address you provide.

street_secondary
Optional
post string PII MTL: 30 DAYS

The additional number and street address of the address.

Example 1
Loading Code Sample...
        
        

        Create an Address

        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
        Parameters
        Parameters in REST API format
        account_sid
        Path
        get sid<AC> Not PII

        The SID of the Account that is responsible for the Address resource to fetch.

        sid
        Path
        get sid<AD> Not PII

        The Twilio-provided string that uniquely identifies the Address resource to fetch.

        Example 1
        Loading Code Sample...
              
              

              Fetch an Address

              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
              Parameters in REST API format
              account_sid
              Path
              get sid<AC> Not PII

              The SID of the Account that is responsible for the Address resource to read.

              customer_name
              Optional
              get string PII MTL: 30 DAYS

              The customer_name of the Address resources to read.

              friendly_name
              Optional
              get string PII MTL: 30 DAYS

              The string that identifies the Address resources to read.

              iso_country
              Optional
              get iso_country_code Not PII

              The ISO country code of the Address resources to read.

              Example 1
              Loading Code Sample...
                    
                    

                    Show all addresses

                    Example 2
                    Loading Code Sample...
                          
                          

                          Show all addresses matching the Customer Name 'Customer 123'

                          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
                                Parameters in REST API format
                                account_sid
                                Path
                                post sid<AC> Not PII

                                The SID of the Account that is responsible for the Address resource to update.

                                sid
                                Path
                                post sid<AD> Not PII

                                The Twilio-provided string that uniquely identifies the Address resource to update.

                                friendly_name
                                Optional
                                post string PII MTL: 30 DAYS

                                A descriptive string that you create to describe the address. It can be up to 64 characters long.

                                customer_name
                                Optional
                                post string PII MTL: 30 DAYS

                                The name to associate with the address.

                                street
                                Optional
                                post string PII MTL: 30 DAYS

                                The number and street address of the address.

                                city
                                Optional
                                post string Not PII

                                The city of the address.

                                region
                                Optional
                                post string Not PII

                                The state or region of the address.

                                postal_code
                                Optional
                                post string PII MTL: 30 DAYS

                                The postal code of the address.

                                emergency_enabled
                                Optional
                                post boolean Not PII

                                Whether to enable emergency calling on the address. Can be: true or false.

                                auto_correct_address
                                Optional
                                post boolean Not PII

                                Whether we should automatically correct the address. Can be: true or false and the default is true. If empty or true, we will correct the address you provide if necessary. If false, we won't alter the address you provide.

                                street_secondary
                                Optional
                                post string PII MTL: 30 DAYS

                                The additional number and street address of the address.

                                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.

                                      Parameters
                                      Parameters in REST API format
                                      account_sid
                                      Path
                                      delete sid<AC> Not PII

                                      The SID of the Account that is responsible for the Address resource to delete.

                                      sid
                                      Path
                                      delete sid<AD> Not PII

                                      The Twilio-provided string that uniquely identifies the Address resource to delete.

                                      Example 1
                                      Loading Code Sample...
                                            
                                            

                                            Delete an Address

                                            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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                            Loading Code Sample...
                                                  
                                                  
                                                  

                                                  Thank you for your feedback!

                                                  Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                  Sending your feedback...
                                                  🎉 Thank you for your feedback!
                                                  Something went wrong. Please try again.

                                                  Thanks for your feedback!

                                                  thanks-feedback-gif