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 regulations, 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 the 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.
Resource properties
city
type: string
The city in which the address is located.
customer_name
type: string
The name associated with the address.This property has a maximum length of 16 4-byte characters, or 21 3-byte characters.
date_created
type: string<date-time-rfc-2822>
date_updated
type: string<date-time-rfc-2822>
friendly_name
type: string
The string that you assigned to describe the resource.
iso_country
type: string<iso-country-code>
The ISO country code of the address.
postal_code
type: string
The postal code of the address.
region
type: string
The state or region of the address.
sid
type: SID<AD>
The unique string that that we created to identify the Address resource.
Pattern:
^AD[0-9a-fA-F]{32}$
street
type: string
The number and street address of the address.
uri
type: string
The URI of the resource, relative to https://api.twilio.com
.
emergency_enabled
type: boolean
Whether emergency calling has been enabled on this number.
validated
type: boolean
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
type: boolean
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
type: string
The additional number and street address of the address.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses.json
Creates a new Address within your account.
URI parameters
Request body parameters
CustomerName
type: stringRequired
The name to associate with the new address.
Street
type: stringRequired
The number and street address of the new address.
City
type: stringRequired
The city of the new address.
Region
type: stringRequired
The state or region of the new address.
PostalCode
type: stringRequired
The postal code of the new address.
IsoCountry
type: string<iso-country-code>Required
The ISO country code of the new address.
FriendlyName
type: string
A descriptive string that you create to describe the new address. It can be up to 64 characters long.
EmergencyEnabled
type: boolean
Whether to enable emergency calling on the new address. Can be: true
or false
.
AutoCorrectAddress
type: boolean
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.
StreetSecondary
type: string
The additional number and street address of the address.
_17// Download the helper library from https://www.twilio.com/docs/node/install
_17// Find your Account SID and Auth Token at twilio.com/console
_17// and set the environment variables. See http://twil.io/secure
_17const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17const authToken = process.env.TWILIO_AUTH_TOKEN;
_17const client = require('twilio')(accountSid, authToken);
_17 customerName: 'customer_name',
_17 postalCode: 'postal_code',
_17 .then(address => console.log(address.sid));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "customer_name": "customer_name",
_18 "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "emergency_enabled": false,
_18 "friendly_name": null,
_18 "postal_code": "postal_code",
_18 "sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "street_secondary": null,
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
If successful, Twilio will respond with a representation of the new address.
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 that 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. |
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{Sid}.json
URI parameters
Sid
type: SID<AD>
The Twilio-provided string that uniquely identifies the Address resource to fetch.
Pattern:
^AD[0-9a-fA-F]{32}$
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.addresses('ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .then(address => console.log(address.customerName));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "customer_name": "name",
_18 "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "emergency_enabled": false,
_18 "friendly_name": null,
_18 "postal_code": "94019",
_18 "sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "street_secondary": null,
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
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].
URI parameters
CustomerName
type: string
The customer_name
of the Address resources to read.
FriendlyName
type: string
The string that identifies the Address resources to read.
IsoCountry
type: string<iso-country-code>
The ISO country code of the Address resources to read.
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.addresses.list({limit: 20})
_10 .then(addresses => addresses.forEach(a => console.log(a.sid)));
_33 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "customer_name": "name",
_33 "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
_33 "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
_33 "emergency_enabled": false,
_33 "friendly_name": null,
_33 "postal_code": "94019",
_33 "sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "street_secondary": null,
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_33 "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=50",
_33 "previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0"
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.addresses.list({customerName: 'Customer 123', limit: 20})
_10 .then(addresses => addresses.forEach(a => console.log(a.sid)));
_33 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "customer_name": "name",
_33 "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
_33 "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
_33 "emergency_enabled": false,
_33 "friendly_name": null,
_33 "postal_code": "94019",
_33 "sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "street_secondary": null,
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_33 "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=50",
_33 "previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0"
Show all phone numbers on your account that require the address AD2a0747eba6abf96b7e3c3ff0b4530f6e
_11// Download the helper library from https://www.twilio.com/docs/node/install
_11// Find your Account SID and Auth Token at twilio.com/console
_11// and set the environment variables. See http://twil.io/secure
_11const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11const authToken = process.env.TWILIO_AUTH_TOKEN;
_11const client = require('twilio')(accountSid, authToken);
_11client.addresses('AD2a0747eba6abf96b7e3c3ff0b4530f6e')
_11 .dependentPhoneNumbers
_11 .then(dependentPhoneNumbers => dependentPhoneNumbers.forEach(d => console.log(d.sid)));
_42 "dependent_phone_numbers": [
_42 "sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_42 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_42 "friendly_name": "3197004499318",
_42 "phone_number": "+3197004499318",
_42 "voice_method": "POST",
_42 "voice_fallback_url": null,
_42 "voice_fallback_method": "POST",
_42 "voice_caller_id_lookup": false,
_42 "date_created": "Thu, 23 Feb 2017 10:26:31 -0800",
_42 "date_updated": "Thu, 23 Feb 2017 10:26:31 -0800",
_42 "sms_method": "POST",
_42 "sms_fallback_url": "",
_42 "sms_fallback_method": "POST",
_42 "address_requirements": "any",
_42 "status_callback": "",
_42 "status_callback_method": "POST",
_42 "api_version": "2010-04-01",
_42 "voice_application_sid": null,
_42 "sms_application_sid": "",
_42 "emergency_status": "Inactive",
_42 "emergency_address_sid": null,
_42 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_42 "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DependentPhoneNumbers.json?Page=0&PageSize=50",
_42 "next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DependentPhoneNumbers.json?Page=50",
_42 "previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DependentPhoneNumbers.json?Page=0&PageSize=50",
_42 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DependentPhoneNumbers.json"
_10GET 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.
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 that satisfy the requirement on a given phone number, this
subresource will not return the phone number in the list.
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.
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 all fields but IsoCountry
can be updated using a POST
request.
To update the IsoCountry
, a new Address must be created.
URI parameters
Sid
type: SID<AD>
The Twilio-provided string that uniquely identifies the Address resource to update.
Pattern:
^AD[0-9a-fA-F]{32}$
Request body parameters
FriendlyName
type: string
A descriptive string that you create to describe the address. It can be up to 64 characters long.
CustomerName
type: string
The name to associate with the address.
Street
type: string
The number and street address of the address.
Region
type: string
The state or region of the address.
PostalCode
type: string
The postal code of the address.
EmergencyEnabled
type: boolean
Whether to enable emergency calling on the address. Can be: true
or false
.
AutoCorrectAddress
type: boolean
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.
StreetSecondary
type: string
The additional number and street address of the address.
Update the customer name and street to ‘Customer 456' and ‘2 Hasselhoff Lane'.
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.addresses('AD2a0747eba6abf96b7e3c3ff0b4530f6e')
_10 .update({customerName: 'Customer 456', street: '2 Hasselhoff Lane'})
_10 .then(address => console.log(address.customerName));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "customer_name": "Customer 456",
_18 "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
_18 "emergency_enabled": false,
_18 "friendly_name": null,
_18 "postal_code": "94019",
_18 "sid": "AD2a0747eba6abf96b7e3c3ff0b4530f6e",
_18 "street": "2 Hasselhoff Lane",
_18 "street_secondary": null,
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
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.
URI parameters
Sid
type: SID<AD>
The Twilio-provided string that uniquely identifies the Address resource to delete.
Pattern:
^AD[0-9a-fA-F]{32}$
_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10client.addresses('ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();