Is anyone using the United States Postal Services (USPS) Address Standardization web service plugin?

2009-09-02 10:13
Written by
CiviCRM has included a plugin for interfacing United States Postal Services (USPS) Address Standardization web service for quite a number of releases. However, the USPS rules for using the service have been a bit hard to pin down and getting authorization from is apparently hit or miss. There have been a few forum posts indicating success using the plugin with CiviCRM versions 1.8 and possibly 1.9. However, since then we've pretty much only had reports of problems related to folks enabling the feature without having a valid account etc. There was also a report on IRC that the protocol for the web service has changed (which means that our plugin might be broken). We are not setup to test this feature - and we're not sure it's a reasonable solution for this problem given the web service access issues. At this point, we're considering hiding or disabling the feature unless or until folks step up and either tell us it's working for them OR commit some resources to get it working with the current web service protocol. If you are using the plugin in your CiviCRM installation - this would be a good time to post back here and let us know about it. Include some details... What version of CiviCRM are you using? Have you modified the code to make it work with the current USPS web service? If we don't hear back from folks, we'll probably hide the feature for the 3.0 release.
Click thumbs up if you thought this blog post was useful (login to vote or to comment)


Folks, I like the thinking process here. Low usage + poor quality = prune. (Not that I want to suggest the quality issues were built in - things have just moved on and the necessary maintenance effort was not warranted).

The CiviCRM user base is becoming a more international crowd (USPS doesn't support Australia!). The functional set is getting bigger. It makes sense to prune stuff. Go for it.

Yes, we use and depend upon the USPS address standardization plug in. Please don't take it away! Currently we are on 2.2.2, and it works flawlessly. The code has not been modified.

You have to be persistent to get an account from USPS. They will send you back and forth between several offices to get sign off.

I just checked on the USPS website, and the documentation has not changed recently. The API docs are dated March 2006. See
I think someone gave you bad information about an API change.

When I left my former parish three weeks ago this feature was working fine. Trinity used this feature to keep all of its addresses accurate and verified. I see no reason to remove it!

Anonymous (not verified)
2009-09-03 - 09:05

The functionality would be very helpful, but from my experience they only give free access if your organization does a lot of shipping, which means more money for them.

I would like to see address standardization using google or yahoo implemented. I hacked the yahoo geocoding script to update all zip codes to zip+4. I don't see why that functionality can't be built in for either the google or yahoo api.

Guest (not verified)
2009-09-03 - 09:00

We're a non-profit organization and evaluating CMS's and one of the features we would like is Canadian address validation. I know this isn't exactly what you're asking but I thought I would comment anyway.

Paul Fisher (not verified)
2009-09-06 - 09:29

I have this feature enabled on two different sites, on two different hosting providers, and it works perfectly fine. I did no modification to the code. I just paid attention to detail when setting up the account with USPS

It works like a charm and even auto-updates on import, which really amazed me. (It would be wise to disable lookup on import by default, as USPS is not a fan of this type of use.) I set an account recently and all went well, except for USPS interactions. Due to everything working perfectly, I think it would be silly to remove this feature.

Here are my lessons learned and an overview of how to get your setup working correctly.

The first task is getting USPS to approve your access to the API. Then making sure your using the production server.

If you are developing a website for a client, I would suggest you have them complete the form for a Web Tools ID themself. As an alternative, I would suggest obtaining explicit permission from the client to enter into the agreement on their behalf using their contact information. For contact email, I would establish a unique email address that the client owns for use with USPS Web Tools, then forward the address to your email while in development.

In this way you can very accurately answer the questions from the standpoint of the website owner, not a developer.

Here are the steps.
1. Register for USPS Web Tools (

b. Will use: "Exclusively on my website"

2. Register your newly acquired Web Tools User ID to request access to the API.

a. Enter the URL of your CiviCRM website (USPS will inspect your website, and look for how it uses the API.)
b. Select your uses
- U.S. Postal Service® package shipments
- U.S. Postal Service letters
* NOTE: Do not select the others, as these uses are not permitted for this API.

- If there are questions, The USPS Internet Customer Care Center (ICCC) will contact you via the listed email address, seeking more information.

3. Request access to the production server.

Once you have been approved to use the API, you should ask for access to the production server. Simply inform them that you are using CiviCRM and it is a fully developed Open Source project, so you do not need to develop anything.

At this stage the ICCC may ask you more specific questions via email.

The USPS needs to hear two things, and hear them very clearly.
a. I am using the information provided only to ship letters or packages via United States Postal Service.
b. The information will be updated when user modify their postal information. They do not want people using this service to batch process addresses.

They also want to see how your website uses the service. Including a URL to your postal address form for users is a good idea. It might even help to make a temp account for them.

You may need to make a phone call to get over the last hurdle, do not expect a return call. However, you will probably get an email stating your account is approved to access the production server.

* Note: It is important that you do not stop the registration process once you have successfully accessed the test server. The test server is not intended for long term use and will probably just halt access eventually, if you do not complete the process.

4. Setup CiviCRM to access the USPS production server

a. paste: into "Web Service URL" on your CiviCRM install ( or through the menu, Administer CiviCRM > Global Settings > Address Settings - [Address Standardization]

* NOTE: This step will do you no good if the ICCC has not granted you access permissions to the production server.

[--- USPS ICCC Directions in the approval email: ---]
1. The Production Server URL is: For APIs calling the secure server, the URL is

2. There is a line of code that refers to "shippingapitest.dll".  You'll need to remove the word "test".

* NOTE: The form for Web Service URL in CiviCRM is not long enough to show the whole URL, therefore some may fail to notice and remove the "test" in the .dll file

****************** For more help *******************

The USPS Internet Customer Care Center (ICCC) is staffed from 7:00AM to 11:00PM Eastern Time.
           Telephone:        1-800-344-7779

[--- Terms of service that may get overlooked: ---]

This unique User ID cannot be shared with others outside your organization, nor is it to be packaged and distributed or sold to other individuals, businesses or e-commerce web site entities.

If the U.S. Postal Service discovers use of the same User ID from more than one web site, all users will be subject to loss of access to the USPS production server

* NOTE: What some may be viewing as technical problems may just be the result of being caught violating the terms of service.

Anonymous (not verified)
2009-09-08 - 16:14

We've tried to use it, unfortunately we never seem to make it through their approval process (unless we were to lie).

I'd much rather use another service that would verify addresses and add the +4 to zip codes. Something that you don't have to jump through a ton of hoops for and is available outside the U.S.

We are a small political campaign and I just signed up to use because we do plenty of mailing and this would help with making sure we maintain valid addresses. Unfortunately I've not been successful yet.

I do not have my site live as we are just now migrating to CiviCRM and trying to correct name and address information.

I applied for authorization to use the production web service but got rejected with the following explanation:

Dear USPS Customer,

Thank you for contacting us. Unfortunately the Address API's can only be used in conjunction with USPS Shipping Services and is not intended for the use of cleansing databases or batch processing.


I have resubmitted the request specifying that we would be using transactional processing. We'll see what happens.

Our USPS CASS Certified™ address validation service matches and corrects mailing addresses using the latest USPS and proprietary data sets available, ensuring your mailing records are always accurate and up-to-date. The service helps improve internal mail processes and ensures cost-saving delivery rates by verifying and standardizing addresses, while flagging for vacancy, returned mail, and general delivery addresses. With the API’s sub-second response times, the service can be used in real-time to help customers and leads correct errors at the time of entry, increasing customer satisfaction and reducing customer service inquiries.

GetBestMatches operation combines Delivery Point Validation (DPV) to verify an address is deliverable, Residential Delivery Indicator (RDI) to identify residential or business, and SuiteLink (SLK) to add secondary suite information for businesses, into one robust API call to our USPS CASS Certified database engine.