Skip to contentSkip to navigationSkip to topbar
Rate this page:
On 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 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.


Address Properties

address-properties page anchor
Resource properties
account_sidtype: SID<AC>Not PII

citytype: stringNot PII

The city in which the address is located.


customer_nametype: stringPII MTL: 30 days

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


date_createdtype: string<DATE TIME RFC 2822>Not PII

The date and time in GMT that the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedtype: string<DATE TIME RFC 2822>Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822(link takes you to an external page) format.


friendly_nametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


iso_countrytype: string<ISO COUNTRY CODE>Not PII

The ISO country code of the address.


postal_codetype: stringPII MTL: 30 days

The postal code of the address.


regiontype: stringNot PII

The state or region of the address.


sidtype: SID<AD>Not PII

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


streettype: stringPII MTL: 30 days

The number and street address of the address.


uritype: stringNot PII

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


emergency_enabledtype: booleanNot PII

Whether emergency calling has been enabled on this number.


validatedtype: booleanNot 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.


verifiedtype: booleanNot 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_secondarytype: stringPII MTL: 30 days

The additional number and street address of the address.


Create an Address resource

create-an-address-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses.json

Creates a new Address within your account.

Parameters

create-parameters page anchor
URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that will be responsible for the new Address resource.


Request body parameters
CustomerNametype: stringPII MTL: 30 days
Required

The name to associate with the new address.


Streettype: stringPII MTL: 30 days
Required

The number and street address of the new address.


Citytype: stringNot PII
Required

The city of the new address.


Regiontype: stringNot PII
Required

The state or region of the new address.


PostalCodetype: stringPII MTL: 30 days
Required

The postal code of the new address.


IsoCountrytype: string<ISO COUNTRY CODE>Not PII
Required

The ISO country code of the new address.


FriendlyNametype: stringPII MTL: 30 days

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


EmergencyEnabledtype: booleanNot PII

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


AutoCorrectAddresstype: booleanNot 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.


StreetSecondarytype: stringPII MTL: 30 days

The additional number and street address of the address.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = require('twilio')(accountSid, authToken);
_17
_17
client.addresses
_17
.create({
_17
customerName: 'customer_name',
_17
street: 'street',
_17
city: 'city',
_17
region: 'region',
_17
postalCode: 'postal_code',
_17
isoCountry: 'US'
_17
})
_17
.then(address => console.log(address.sid));

Output

_18
{
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"city": "city",
_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
"iso_country": "US",
_18
"postal_code": "postal_code",
_18
"region": "region",
_18
"sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"street": "street",
_18
"street_secondary": null,
_18
"validated": false,
_18
"verified": false,
_18
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_18
}

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

Address Validation Related Errors

av-errors page anchor
Error CodeError NameError Description
21615Phone Number Requires a Local AddressTo purchase this number you must have an Address on your account that satisfies the local address requirements.
21628Address Validation ErrorThe address you have provided cannot be validated.
21629Address Validation Error - Check Suggested AddressThe 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

fetch-an-address-resource page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Addresses/{Sid}.json

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that is responsible for the Address resource to fetch.


Sidtype: SID<AD>Not PII
Path Parameter

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.addresses('ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(address => console.log(address.customerName));

Output

_18
{
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"city": "SF",
_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
"iso_country": "US",
_18
"postal_code": "94019",
_18
"region": "CA",
_18
"sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"street": "4th",
_18
"street_secondary": null,
_18
"validated": false,
_18
"verified": false,
_18
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_18
}


Read multiple Address resources

read-multiple-address-resources page anchor
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
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that is responsible for the Address resource to read.


CustomerNametype: stringPII MTL: 30 days
Query Parameter

The customer_name of the Address resources to read.


FriendlyNametype: stringPII MTL: 30 days
Query Parameter

The string that identifies the Address resources to read.


IsoCountrytype: string<ISO COUNTRY CODE>Not PII
Query Parameter

The ISO country code of the Address resources to read.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.addresses.list({limit: 20})
_10
.then(addresses => addresses.forEach(a => console.log(a.sid)));

Output

_33
{
_33
"addresses": [
_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"city": "SF",
_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
"iso_country": "US",
_33
"postal_code": "94019",
_33
"region": "CA",
_33
"sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"street": "4th",
_33
"street_secondary": null,
_33
"validated": false,
_33
"verified": false,
_33
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_33
}
_33
],
_33
"end": 0,
_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
"num_pages": 1,
_33
"page": 0,
_33
"page_size": 50,
_33
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33
"start": 0,
_33
"total": 1,
_33
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0"
_33
}

Show all addresses matching the Customer Name 'Customer 123'

show-all-addresses-matching-the-customer-name-customer-123 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.addresses.list({customerName: 'Customer 123', limit: 20})
_10
.then(addresses => addresses.forEach(a => console.log(a.sid)));

Output

_33
{
_33
"addresses": [
_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"city": "SF",
_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
"iso_country": "US",
_33
"postal_code": "94019",
_33
"region": "CA",
_33
"sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"street": "4th",
_33
"street_secondary": null,
_33
"validated": false,
_33
"verified": false,
_33
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_33
}
_33
],
_33
"end": 0,
_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
"num_pages": 1,
_33
"page": 0,
_33
"page_size": 50,
_33
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0",
_33
"start": 0,
_33
"total": 1,
_33
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses.json?PageSize=50&Page=0"
_33
}

List Dependent PNS Subresources

list-dependent-pns-subresources page anchor

Show all phone numbers on your account that require the address AD2a0747eba6abf96b7e3c3ff0b4530f6e

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.addresses('AD2a0747eba6abf96b7e3c3ff0b4530f6e')
_11
.dependentPhoneNumbers
_11
.list({limit: 20})
_11
.then(dependentPhoneNumbers => dependentPhoneNumbers.forEach(d => console.log(d.sid)));

Output

_42
{
_42
"dependent_phone_numbers": [
_42
{
_42
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_42
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_42
"friendly_name": "3197004499318",
_42
"phone_number": "+3197004499318",
_42
"voice_url": null,
_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_url": "",
_42
"sms_method": "POST",
_42
"sms_fallback_url": "",
_42
"sms_fallback_method": "POST",
_42
"address_requirements": "any",
_42
"capabilities": {
_42
"Voice": false,
_42
"SMS": true,
_42
"MMS": false
_42
},
_42
"status_callback": "",
_42
"status_callback_method": "POST",
_42
"api_version": "2010-04-01",
_42
"voice_application_sid": null,
_42
"sms_application_sid": "",
_42
"trunk_sid": null,
_42
"emergency_status": "Inactive",
_42
"emergency_address_sid": null,
_42
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_42
}
_42
],
_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
"page": 0,
_42
"page_size": 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"
_42
}


Read multiple Address Subresources

instance-subresources page anchor

_10
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

list-dependent-pns page anchor

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.


Update an Address resource

update-an-address-resource page anchor
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
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that is responsible for the Address resource to update.


Sidtype: SID<AD>Not PII
Path Parameter

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


Request body parameters
FriendlyNametype: stringPII MTL: 30 days

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


CustomerNametype: stringPII MTL: 30 days

The name to associate with the address.


Streettype: stringPII MTL: 30 days

The number and street address of the address.


Citytype: stringNot PII

The city of the address.


Regiontype: stringNot PII

The state or region of the address.


PostalCodetype: stringPII MTL: 30 days

The postal code of the address.


EmergencyEnabledtype: booleanNot PII

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


AutoCorrectAddresstype: booleanNot 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.


StreetSecondarytype: stringPII MTL: 30 days

The additional number and street address of the address.

Update a customer name and street address

update-a-customer-name-and-street-address page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.addresses('AD2a0747eba6abf96b7e3c3ff0b4530f6e')
_10
.update({customerName: 'Customer 456', street: '2 Hasselhoff Lane'})
_10
.then(address => console.log(address.customerName));

Output

_18
{
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"city": "SF",
_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
"iso_country": "US",
_18
"postal_code": "94019",
_18
"region": "CA",
_18
"sid": "AD2a0747eba6abf96b7e3c3ff0b4530f6e",
_18
"street": "2 Hasselhoff Lane",
_18
"street_secondary": null,
_18
"validated": false,
_18
"verified": false,
_18
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Addresses/ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_18
}


Delete an Address resource

delete-an-address-resource page anchor
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
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that is responsible for the Address resource to delete.


Sidtype: SID<AD>Not PII
Path Parameter

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.addresses('ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: