Twilio Address Provider

🎯 Overview

The Address API Provider (Providers/address-api.js) manages address creation and validation required for regulatory compliance when purchasing phone numbers in certain countries.

Source: external/Integrations/Twilio/Providers/address-api.js

Key Capabilities:

• Create addresses for compliance
• Retrieve address details
• List all addresses
• Update address information
• Delete addresses

Why Addresses Matter:

• Regulatory Compliance: Many countries require verified addresses
• E911 Services: Emergency services require physical address
• A2P Registration: US A2P 10DLC requires business address
• Number Provisioning: Some numbers cannot be purchased without address

🔌 Provider Functions

create()

Create a new address for phone number compliance.

Signature:

exports.create = async({ address, accountSID, authToken });

Parameters:

Parameter	Type	Required	Description
address	Object	✅	Address details
accountSID	String	✅	Twilio Account SID
authToken	String	✅	Twilio Auth Token

address Object:

Field	Type	Required	Description
customerName	String	✅	Customer or business name
street	String	✅	Street address
city	String	✅	City
region	String	✅	State/province/region
postalCode	String	✅	ZIP/postal code
isoCountry	String	✅	ISO 3166-1 alpha-2 country code (US, GB)
streetSecondary	String	❌	Apartment, suite, floor, etc.
friendlyName	String	❌	Display name for address

Returns:

Promise<{
  sid: string; // Address SID (AD...)
  accountSid: string;
  customerName: string;
  friendlyName: string;
  street: string;
  streetSecondary: string;
  city: string;
  region: string;
  postalCode: string;
  isoCountry: string;
  emergencyEnabled: boolean;
  validated: boolean; // Whether Twilio validated the address
  verified: boolean; // Whether address verification was successful
  dateCreated: Date;
  dateUpdated: Date;
  uri: string;
}>;

Example Usage:

const addressProvider = require('./Providers/address-api');

// Create business address
const address = await addressProvider.create({
  address: {
    customerName: 'DashClicks LLC',
    street: '123 Main Street',
    streetSecondary: 'Suite 100',
    city: 'New York',
    region: 'NY',
    postalCode: '10001',
    isoCountry: 'US',
    friendlyName: 'Headquarters',
  },
  accountSID: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
});

console.log('Address SID:', address.sid); // AD1234567890abcdef
console.log('Validated:', address.validated); // true
console.log('Verified:', address.verified); // true

Create Individual Address:

// Individual address for regulatory compliance
const address = await addressProvider.create({
  address: {
    customerName: 'John Doe',
    street: '456 Elm Street',
    city: 'Los Angeles',
    region: 'CA',
    postalCode: '90001',
    isoCountry: 'US',
  },
  accountSID,
  authToken,
});

---

getAnAddress()

Retrieve details of a specific address by SID.

Signature:

exports.getAnAddress = async({ sid, accountSID, authToken });

Parameters:

Parameter	Type	Required	Description
sid	String	✅	Address SID (AD...)
accountSID	String	✅	Twilio Account SID
authToken	String	✅	Twilio Auth Token

Returns:

Promise<TwilioAddressInstance>;

Example Usage:

// Get address details
const address = await addressProvider.getAnAddress({
  sid: 'AD1234567890abcdef1234567890abcdef',
  accountSID: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
});

console.log('Customer:', address.customerName);
console.log(
  'Address:',
  `${address.street}, ${address.city}, ${address.region} ${address.postalCode}`,
);
console.log('Validated:', address.validated);

---

getAllAddresses()

List all addresses for an account.

Signature:

exports.getAllAddresses = async({ accountSID, authToken });

Parameters:

Parameter	Type	Required	Description
accountSID	String	✅	Twilio Account SID
authToken	String	✅	Twilio Auth Token

Returns:

Promise<Array<TwilioAddressInstance>>;

Example Usage:

// Get all addresses
const addresses = await addressProvider.getAllAddresses({
  accountSID: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
});

console.log('Total addresses:', addresses.length);

addresses.forEach(addr => {
  console.log(`${addr.friendlyName || addr.customerName} (${addr.sid})`);
  console.log(`  ${addr.street}, ${addr.city}, ${addr.region}`);
  console.log(`  Validated: ${addr.validated}`);
});

---

updateAddress()

Update an existing address.

Signature:

exports.updateAddress = async({ sid, accountSID, authToken, addressObject });

Parameters:

Parameter	Type	Required	Description
sid	String	✅	Address SID to update
accountSID	String	✅	Twilio Account SID
authToken	String	✅	Twilio Auth Token
addressObject	Object	✅	Fields to update

addressObject (all fields optional):

{
  customerName: 'Updated Name',
  street: 'New Street',
  streetSecondary: 'New Suite',
  city: 'New City',
  region: 'NY',
  postalCode: '10002',
  friendlyName: 'New Name'
}

Returns:

Promise<TwilioAddressInstance>;

Example Usage:

// Update address
const updated = await addressProvider.updateAddress({
  sid: 'AD1234567890abcdef',
  accountSID,
  authToken,
  addressObject: {
    street: '789 New Street',
    streetSecondary: 'Floor 5',
    postalCode: '10002',
  },
});

console.log('Updated address:', updated.street);

---

deleteAddress()

Delete an address.

Signature:

exports.deleteAddress = async({ sid, accountSID, authToken });

Parameters:

Parameter	Type	Required	Description
sid	String	✅	Address SID to delete
accountSID	String	✅	Twilio Account SID
authToken	String	✅	Twilio Auth Token

Returns:

Promise<true>;

Example Usage:

// Delete address
await addressProvider.deleteAddress({
  sid: 'AD1234567890abcdef',
  accountSID,
  authToken,
});

console.log('Address deleted');

⚠️ WARNING: Cannot delete addresses that are associated with active phone numbers or bundles.

---

💡 Integration Examples

Address for Phone Number Purchase

async function purchaseNumberWithAddress(phoneNumber, businessInfo) {
  // 1. Create address
  const address = await addressProvider.create({
    address: {
      customerName: businessInfo.name,
      street: businessInfo.street,
      city: businessInfo.city,
      region: businessInfo.state,
      postalCode: businessInfo.zip,
      isoCountry: 'US',
      friendlyName: 'Business Address',
    },
    accountSID: businessInfo.twilioAccountSid,
    authToken: businessInfo.twilioAuthToken,
  });

  // 2. Purchase number with address SID
  const numberProvider = require('./number-api');
  const number = await numberProvider.addProvisionNumber(
    businessInfo.twilioAccountSid,
    businessInfo.twilioAuthToken,
    {
      phoneNumber,
      addressSid: address.sid,
      smsUrl: process.env.TWILIO_SMS_URL,
      voiceUrl: process.env.TWILIO_VOICE_URL,
    },
  );

  return { address, number };
}

E911 Emergency Services Setup

async function setupE911Address(phoneNumberSid, emergencyAddress) {
  // 1. Create emergency address
  const address = await addressProvider.create({
    address: {
      customerName: emergencyAddress.name,
      street: emergencyAddress.street,
      city: emergencyAddress.city,
      region: emergencyAddress.state,
      postalCode: emergencyAddress.zip,
      isoCountry: 'US',
      friendlyName: 'E911 Address',
    },
    accountSID,
    authToken,
  });

  // 2. Update phone number with emergency address
  const numberProvider = require('./number-api');
  await numberProvider.updateProvisionNumber(accountSID, authToken, phoneNumberSid, {
    emergencyEnabled: true,
    emergencyAddressSid: address.sid,
  });

  return address;
}

Address Management Dashboard

async function getAddressDashboard(accountSID, authToken) {
  const addresses = await addressProvider.getAllAddresses({ accountSID, authToken });

  return {
    total: addresses.length,
    validated: addresses.filter(a => a.validated).length,
    verified: addresses.filter(a => a.verified).length,
    byCountry: addresses.reduce((acc, addr) => {
      acc[addr.isoCountry] = (acc[addr.isoCountry] || 0) + 1;
      return acc;
    }, {}),
    addresses: addresses.map(addr => ({
      sid: addr.sid,
      name: addr.friendlyName || addr.customerName,
      address: `${addr.street}, ${addr.city}, ${addr.region} ${addr.postalCode}`,
      country: addr.isoCountry,
      validated: addr.validated,
      verified: addr.verified,
      emergencyEnabled: addr.emergencyEnabled,
    })),
  };
}

Validate and Update Address

async function validateAndUpdateAddress(addressSid, updates) {
  // 1. Get current address
  const current = await addressProvider.getAnAddress({
    sid: addressSid,
    accountSID,
    authToken,
  });

  // 2. Update address
  const updated = await addressProvider.updateAddress({
    sid: addressSid,
    accountSID,
    authToken,
    addressObject: updates,
  });

  // 3. Check validation status
  if (!updated.validated) {
    throw new Error('Address validation failed. Please verify the address details.');
  }

  return {
    previous: {
      street: current.street,
      city: current.city,
      validated: current.validated,
    },
    updated: {
      street: updated.street,
      city: updated.city,
      validated: updated.validated,
    },
  };
}

Clean Up Unused Addresses

async function cleanupUnusedAddresses(accountSID, authToken) {
  // 1. Get all addresses
  const addresses = await addressProvider.getAllAddresses({ accountSID, authToken });

  // 2. Get all phone numbers
  const numberProvider = require('./number-api');
  const numbers = await TwilioNumber.find({ accountSid: accountSID });

  // 3. Find addresses not used by any number
  const usedAddressSids = numbers.map(n => n.emergencyAddressSid).filter(Boolean);

  const unusedAddresses = addresses.filter(addr => !usedAddressSids.includes(addr.sid));

  // 4. Delete unused addresses
  const deleted = [];
  for (const addr of unusedAddresses) {
    try {
      await addressProvider.deleteAddress({
        sid: addr.sid,
        accountSID,
        authToken,
      });
      deleted.push(addr.sid);
    } catch (error) {
      console.error(`Failed to delete ${addr.sid}:`, error.message);
    }
  }

  return {
    total: addresses.length,
    unused: unusedAddresses.length,
    deleted: deleted.length,
  };
}

---

🚨 Error Handling

Common Errors

1. Address Validation Failed

Error: 21215 - Address validation failed

• Cause: Address format or details are invalid
• Solution: Verify address matches postal service records

2. Missing Required Fields

Error: 21201 - Missing required parameter

• Cause: Required address field not provided
• Solution: Provide all required fields (customerName, street, city, region, postalCode, isoCountry)

3. Address In Use

Error: 20403 - Cannot delete address in use

• Cause: Address associated with active phone number or bundle
• Solution: Remove address from phone number/bundle first

4. Invalid Country Code

Error: 21401 - Invalid Country Code

• Cause: isoCountry not in ISO 3166-1 alpha-2 format
• Solution: Use 2-letter codes (US, GB, CA, not USA, UK, CAN)

---

⚡ Performance Considerations

• Address Validation: Twilio validates addresses against postal service data (may take 1-2 seconds)
• Caching: Consider caching address list for dashboard views
• Batch Operations: No batch API - create addresses one at a time
• Reuse: Reuse validated addresses for multiple phone numbers

---

🔗 Related Documentation

• Twilio Integration Overview - Main Twilio integration
• Phone Numbers - Associate addresses with numbers
• A2P Provider - A2P registration with addresses
• Regulatory Compliance - Compliance requirements

External Resources:

• Twilio Addresses API
• E911 Setup
• Address Validation