Address Verification Package


The address validation package provided by xTuple is designed to verify the accuracy of the addresses you enter. This package is especially critical for anyone using the Avalara tax service integration, since Avalara requires valid addresses when calculating sales tax information.

Note: The package currently validates United States Postal Service (USPS) addresses only. Support for other address systems may be added in future.

The package allows you to validate addresses anywhere in xTuple where addresses are used: on company and contact records, sales orders, purchase orders, and more. Plus, you don't even need the Avalara integration to make use of it.

Getting Started

Begin by installing the xTuple Address Validation package into your xTuple database using the Updater application. Please contact your xTuple support representative if you need access to download the software.

Tip: Once the package is installed, be sure to grant users the CRM module privileges associated with address validation.

To configure the package, you must have a USPS web tools user account. This is required, as the package will not work without it. To register a user account with USPS, follow these steps:

  1. In a web browser, navigate to the USPS Web Tools API page.
  2. Select the REGISTER NOW button.
  3. Fill out and then submit the registration form.
  4. Once registered with USPS, obtain your User Id and URL for the API (i.e.,

With this information, go to the following location in xTuple ERP: CRM > Setup > Configure


Configuring the address validation package

When configuring the address validation system, you are presented with the following options:

IMPORTANT NOTE: Contact names are not considered part of an address.  As a result, there is no line for contact name in the address fields.

  • User Id: Enter your USPS user id here. The user id will be supplied to you by USPS, after you register an account on their site.
  • URL: Leave this field blank, allowing the "grayed out" default URL to be displayed. You may override this default URL if (a) USPS changes their official URL or (b) your network rules require it.
  • How do you want to use the street address?:  The validation of addresses can be configured to match the way you handle addresses in xTuple. As long as you include the main elements, the USPS lookup will work in any order. Contact names are not considered part of an address. For each address line, choose one of the following options.
    • Name of company at this address: The name of the company appears in this line of the address. This is optional.
    • Main street address: The main street address appears in this line.
    • Apartment, suite, etc.: Apartment, suite, or similar information appears in this line. This optional.
    • Urbanization (required for Puerto Rico): If the address is in Puerto Rico, use this line for urbanization information. This is optional.
    • [ unvalidated ]: Select if the line should be ignored, as in the case where you don't use the line, for example. This optional.
  • Show Hints: Select to provide users with line-by-line directions when they are entering addresses. If not selected, address hints will not be shown.
  • Supported Countries: Displays the list of supported countries. Currently, only United States addresses are supported.

Once you complete the configuration steps, you will now be able to validate addresses when entering them in xTuple. The following screenshot shows a typical address screen, including the address validation features:


Address screen with validation features

As you can see in the screenshot, each line of the address shows an underlying hint about which information belongs in each line. The hints for each line will mirror the options you choose in your configuration.

Also notice the CHECK button in the lower right corner of the address. Once an address has been entered, choose this button to validate the address against the database of valid USPS addresses. If the address is valid, the button will change and display as GOOD. However, if the address is invalid, you will see a warning message and the button will display as INVALID.

NOTE: Having valid addresses is essential when using the Avalara tax service integration. With xTuple address validation features, you can ensure that the addresses you enter are correct.





How It Works

Enter content