Bulk Address Verification API - US, Canada and Worldwide

Clean a mailing list before you spend money on it: verify, correct and standardize postal addresses in the US, Canada and worldwide, in batches of up to 2000 addresses per call.

What it does

• Two coverage areas, one output shape. The US and Canada service returns USPS and Canada Post detail. The worldwide service covers the rest of the world with a formatted address and a match score. Both write the same core columns, so results from the two are comparable side by side.
• Corrects rather than only judging. An address comes back standardized, with the status saying whether it was already right, was corrected, or failed. A typo in a street name, a missing direction or a wrong city are fixed rather than reported.
• Returns the detail that decides postage. ZIP+4, county and FIPS code, carrier route, delivery point validation, eLOT sequence, residential and vacancy flags, time zone and area code.
• Geocodes as it verifies. Latitude, longitude and an accuracy level, at rooftop level where the data supports it, without a second lookup.
• Takes freeform or structured input. A single line pasted from a form, or the separate columns you already hold. Common spreadsheet column names are accepted and rewritten to the provider's own.
• Batches up to the provider's ceiling. 2000 addresses per call, at a batch size you control, because a batch larger than the lookups left on your account fails as a whole.
• Suggests candidates when an address fails. Suggestion mode answers "what might this have meant", including unit number ranges for a building.
• Parses one line into components. House number, road, unit, floor, PO box, postcode, suburb, city district, city, county, state and country.
• Goes both ways on postal codes. A ZIP or postal code returns the cities and counties it covers with the mailable flag, and a US city and state returns every ZIP code inside it.
• Keeps the misses. An address nobody could verify still produces a row saying so, and rows this actor refused before sending are never charged for.

Input

Verify a list of addresses

{
  "mode": "verify",
  "addresses": [
    "111 Deerwood Rd Ste 200, San Ramon CA 94583 US",
    "20 Bay St, Toronto ON M5J 2N8 CA"
  ],
  "includeDetails": true,
  "maxResults": 1000
}

Verify addresses you hold as columns

{
  "mode": "verify",
  "structuredAddresses": [
    { "line1": "90 Canal St", "city": "Boston", "provinceOrState": "MA", "postalOrZip": "02114", "country": "US", "id": "row-1" },
    { "line1": "20-20 Bay St", "city": "Toronto", "provinceOrState": "ON", "postalOrZip": "M9V 4V1", "country": "CA", "id": "row-2" }
  ],
  "batchSize": 500
}

Verify addresses outside North America

{
  "mode": "verifyInternational",
  "addresses": ["Sageweg 27, 79395 Neuenburg, DE"],
  "geoData": true
}

Example output

One row per address.

{
  "input": "111 Deerwood Rd Ste 200, San Ramon CA 94583 US",
  "coverage": "us_ca",
  "status": "corrected",
  "verified": true,
  "corrected": true,
  "line1": "111 DEERWOOD RD STE 200",
  "city": "SAN RAMON",
  "provinceOrState": "CA",
  "provinceOrStateName": "CALIFORNIA",
  "postalOrZip": "94583",
  "zipPlus4": "4445",
  "country": "us",
  "countryName": "UNITED STATES",
  "streetNumber": "111",
  "streetName": "DEERWOOD",
  "streetType": "RD",
  "suiteKey": "STE",
  "suiteID": "200",
  "county": "CONTRA COSTA",
  "countyFIPS": "13",
  "residential": false,
  "vacant": false,
  "carrierRoute": "C027",
  "dpvConfirmation": "Y",
  "latitude": 37.7659,
  "longitude": -121.9585,
  "geocodeAccuracy": "rooftop"
}

Frequently asked questions

What is the difference between the US and Canada mode and the worldwide mode?

They are two different services at the provider, with different data behind them. The US and Canada service is built on USPS and Canada Post data and returns postal detail: ZIP+4, carrier route, delivery point validation, county and a rooftop geocode. The worldwide service covers more than 240 countries and returns a formatted address, a verification status, a match level and a match score instead. Pick the one that matches where your list is, and run the list twice if it spans both.

Does it correct addresses or only check them?

It corrects them. A verified address comes back in the postal authority's own standardized form, with the status saying whether the input was already correct or had to be changed. The status is verified when the input was right, corrected when the provider fixed something, and failed when no real address matches.

Can I verify addresses in bulk?

Yes. Up to 2000 addresses go in one call, and the batch size is yours to set. Bear in mind that a batch larger than the lookups remaining on your account fails as a whole rather than in part, so a smaller batch size is safer when an allowance is nearly used up.

What is ZIP+4 and why does it matter?

ZIP+4 is the four digit extension the USPS adds to a five digit ZIP code to identify a specific block, building or delivery point. Mail sorted with it qualifies for lower postage rates and gets delivered more reliably, which is usually the reason a mailing list gets verified in the first place.

Can I tell residential addresses from business addresses?

Yes, on US addresses. The detail block carries a residential flag, a vacancy flag and the delivery point validation indicator, which together tell you whether an address is a home, a business, and whether anybody is currently receiving mail there.

What happens to an address that cannot be verified?

It still produces a row, with verified set to false and the provider's own error notes saying what was wrong, for example a missing suite identifier or a typo in the street name. Suggestion mode then takes the same address and returns the candidates it might have meant, which is the usual next step for a list that is mostly good with a bad tail.

Do I need my own API key?

Yes. This actor is bring your own key: it calls the address verification API using your own account key, so you keep your own lookup allowance, your own rate limits and your own data agreement. Create the key in the provider's dashboard under Developers, and use a live key rather than a test key, because a test key only answers test data.

How many free lookups do I get?

That is set by your own account rather than by this actor. The run reports how many of the free lookups on your key have been used and how many are left before it starts, so a run that is about to exhaust an allowance says so rather than failing halfway through.

How much does a run cost?

Charging is per row, and only rows the provider answered are charged. A confirmed undeliverable address counts as an answer, because the provider spent a lookup to establish it. Rows this actor refused before sending, and batches the provider would not process, are free. Set maxResults to cap the rows a run can produce.

What are the rate limits?

The provider documents five requests a second with a throughput of about 100 addresses a second. This actor paces itself at 120 requests a minute by default and is capped at 240, which leaves headroom on an account that is also serving your own application. Because batching sends up to 2000 addresses in one request, the request rate is rarely the limit that matters.

Keyword map

address verification API, address validation API, bulk address verification, USPS address validation, CASS address standardization, ZIP+4 lookup, Canada Post address verification, international address verification, global address validation, address autocomplete API, address parsing API, address suggestion API, ZIP code lookup by city, city and state from ZIP code, delivery point validation, DPV confirmation, residential or business address, address geocoding API, mailing list cleaning, direct mail address hygiene