E911 Address Enablement using The Twilio REST API – Twilio Support

INTRODUCTION

The registration of E911 Address Enablement utilizing Twilio's REST API can help users perform individual, or bulk tasks programmatically, but how are locations - e.g.: Unit, Building, Suite, et al - handled?

This guide is intended to point out appropriate MSAG address formatting to ensure Emergency Address Enablement is compliant with MSAG address formatting.

What is MSAG?

Master Street Address Guide (MSAG) is a database that contains the streets and addresses in their associated postal range that emergency services use to link a Phone Number to a physical Address. A state or municipal authority manages the MSAG database authority and the state/municipal authority is responsible for updating their respective MSAG directory and making the directory available for use.

What MSAG Is NOT

In the US, the MSAG address will often differ from the equivalent US Postal Service address because the MSAG uses the community name (township, city, county) from where the closest responding PSAP will come.

GETTING STARTED

Before we begin, we must ensure our Twilio Helper Libraries meet the minimum versioning to include the location parameter known as Street Secondary.

Why is Street Secondary important?

We introduced the Street Secondary parameter to the Twilio Helper Libraries in December 2022, some Customer's may be using an older helper library version that does not include the Street Secondary parameter.

*Addresses using older Twilio Helper Libraries will result in incorrect formatting of the Emergency Address, which can lead to Address enablement rejections - due to strict MSAG formatting rules.

This can result in a $75 charge per E911 dial, as per the Emergency Calling for SIP Trunking documentation.

In the US and Canada, when a 911 call is placed from a phone number without a registered emergency address, Twilio will charge a $75 fee per 911 call for the call to be delivered to a national emergency location center. To avoid this charge, associate a validated emergency address with your phone numbers. Associating an emergency address with a phone number has a cost of $0.75 per phone number per month.

Twilio Helper Library spot-check

Let us begin with a Twilio Helper Library (Helper Library) spot-check.

Helper Library version support

The Street Secondary parameter is supported from these Helper Library versions forward.

Twilio Helper Library	Minimum Supported Version	Parameter
PHP	6.44.0	`street_secondary`
Node	3.84.0	`streetSecondary`***
C#/.NET	6.2.0	`StreetSecondary`***
Java	9.2.0	`street_secondary`
Python	7.16.0	`street_secondary`
Ruby	5.74.0	`street_secondary`
GO	1.3.0	`params.SetStreetSecondary`***

*** Parameter syntax is misrepresented in GitHub.

Please note: When upgrading your Helper Library versions, check the minimum package requirements for your language - e.g.: The supported Node.js versions for Twilio helper libraries include Node.js 14/16/18.

Version Check

Before we add a new Address - or update an existing one - we recommend a version check. We will spot check the Node.js and Python Helper libraries.

Node.js Helper Library version check

You can check your Node.js and Helper Library version with the following commands.

node --version
<Version response will print here>
npm -v twilio
<Version response will print here>

I am using Node.js v18.15.0 (supported) and the latest Twilio Helper Library 9.5.0, when writing this document.

Please note: The streetSecondary parameter is available on Helper Library version 3.84.0 forward.

Python Helper Library version check

You can check your Python and Helper Library version with the following commands.

python3 --version
<Version response will print here>
pip3 show twilio
<Version response will print here>

I am using Python 3 version 3.9.2 and the latest Twilio Helper Library 7.17.0, when writing this document

Please note: The street_secondary parameter is available on Helper Library version 7.16.0 forward.

ADDING AN ADDRESS WITH THE STREET SECONDARY PARAMETER

Now that we have confirmed the minimum version requirements for the Street Secondary parameter, we can proceed with the creation of an MSAG formatted address. For Node.js we will use the code snippet below to add a new Address to our Twilio Console:

create_address.js

// Download the helper library from https://www.twilio.com/docs/node/install
// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.addresses
      .create({
         customerName: 'G',
         friendlyName: 'G',
         street: '333 S Grand Avenue',
         streetSecondary: 'Suite 3310',
         city: 'Los Angeles',
         region: 'CA',
         postalCode: '90071',
         isoCountry: 'US',
         autoCorrectAddress: 'true',
         emergencyEnabled: 'true'
       })
      .then(address => console.log(address));

MSAG Address Suggestions

When adding - or updating an existing Address, you may encounter an error/exception, Twilio's REST API validates the address prior to addition and may respond with an exception and 'suggest' an address adjustment. The address suggestion comes in many forms and generally suggests changes to:

Locality
Postal Code
Street, Avenue, Boulevard, et al abbreviations

In the script above we are requesting an Address creation with street: '333 S Grand Avenue', this is not an acceptable MSAG formatted address as you can see below:

Address Creation Exception and Suggestion

In the screen cast above, the suggested address recommends Street: 333 S GRAND AVE:

Projects/gexters-laboratory/addressResource via  v18.15.0 on ☁️  (us-east-1)
❯ node create_address.js
/Users/username/Projects/gexters-laboratory/node_modules/twilio/lib/base/Version.js:79
                throw new RestException_1.default(response);
                      ^

RestException [Error]: The requested address was not validated. Please check the suggested address. | CustomerName: G, Locality: LOS ANGELES, Region: CA, PostalCode: 90071, Street: 333 S GRAND AVE, StreetSecondary: Suite 3310, FriendlyName: Suite 3310, IsoCountry: US
    at success (/Users/username/Projects/gexters-laboratory/node_modules/twilio/lib/base/Version.js:79:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5) {
  status: 400,
  code: 21629,
  moreInfo: 'https://www.twilio.com/docs/errors/21629',
  details: undefined
}

The recommend Street parameter is Street: 333 S GRAND AVE, changing the abbreviation of Avenue to AVE results in a successful Address creation.

Address Creation with Suggested Abbreviation

Modifying 333 S Grand Avenue to 333 S Grand Ave results in a successful address creation.

Projects/gexters-laboratory/addressResource via  v18.15.0 on ☁️  (us-east-1)
❯ node create_address.js
{
  accountSid: 'ACxxx',
  city: 'Los Angeles',
  customerName: 'G',
  dateCreated: 2023-03-26T21:42:10.000Z,
  dateUpdated: 2023-03-26T21:42:10.000Z,
  friendlyName: 'Suite 3310',
  isoCountry: 'US',
  postalCode: '90071',
  region: 'CA',
  sid: 'ADxxx',
  street: '333 S Grand Ave',
  uri: '/2010-04-01/Accounts/ACxxx/Addresses/ADxxx.json',
  emergencyEnabled: true,
  validated: true,
  verified: false,
  streetSecondary: 'Suite 3310'
}

Updating an existing Address Resource

Please see our Update an Address resource documentation for instructions on updating an existing Address Resource, if you are using a 'Location', be sure to include the Street Secondary parameter.

Please note: If you are updating a Emergency Enabled Address, you must remove ALL Phone Number associations prior to updating the Address Resource. For more information please review our How to Unregister an Emergency Address from a Twilio Phone Number article.

Deleting an existing Address Resource

Please see our Update an Address resource documentation for instructions on deleting and existing Address Resource.

SUMMARY

To summarize, the Emergency Address REST API is a power tool that empowers our Customer's with the ability to add single or bulk Addresses to your Twilio account; please remember to follow any exception(s) and suggestion(s) when creating/updating your Emergency Addresses - if you have a 'Location' value, e.g.: Suite, Unit, Building, et al - be sure to include the Street Secondary parameter.

If you believe the exception and suggestion values do not match your address information, please open a support ticket and our team will be happy to review and validate your Emergency Address.

ADDITIONAL CONSIDERATIONS

Emergency Address enablement relies on a conditional rule-set dependent on proper MSAG formatting, to ensure your Emergency Address(es) validate successfully please be sure to:

Limit your Customer Name and Friendly Name to 32 alpha-numeric characters, this includes spaces.
Modify any suggestions provided when your response includes an exception.
Open a support ticket when an Address creation/update request 'exception/suggestion' does not match the values of your Address - i.e.: Wrong Zip Code, Locality, invalid Geo Coordinates, et al.
Include a Customer Name with the Friendly Name.
Postal Codes must be provided in the 5-digit format, 9-digit postal code formats are not valid.
Be sure not to use symbols like "&", "@", "#" in the Friendly Name, Customer Name, or Addressing fields (Secondary address field is OK as that field is not passed to the vendor).
Be sure NOT to add any extra spaces before or after any of the Addressing fields.
PO Boxes should NEVER be used for E911 addresses