Address Validation API - USPS ZIP+4 and 240 Countries

Validate, correct and standardize any postal address against USPS and international postal authority data, and get back the deliverable version with ZIP+4, DPV deliverability codes and rooftop coordinates.

What it does

• Verifies US addresses against USPS data. Returns the standardized delivery line, the ZIP+4 add-on, the 12 digit delivery point barcode and the DPV match code that says whether mail is actually deliverable there.
• Verifies international addresses in over 240 countries. Returns the address formatted the way that country's postal authority writes it, either in the local script or transliterated to Latin characters.
• Separates "wrong" from "does not exist". DPV footnotes distinguish a missing apartment number from a building that is vacant, a commercial mail receiving agency, or a street that has no such house number.
• Geocodes while it verifies. Every US result carries latitude, longitude and a precision level from ZIP centroid up to rooftop, so a single call replaces a verification step and a geocoding step.
• Returns residential or commercial. The RDI flag is what shipping rate calculators need in order to apply residential surcharges correctly.
• Adds county, carrier route, congressional district and time zone. The metadata that tax lookup, territory assignment and delivery window logic are usually missing.
• Explains every correction. Turn on component analysis and each part of the address reports whether it was confirmed, changed, added or missing.
• Accepts messy input. A single line string, a spreadsheet row with a zip column, or the provider's own field names all work. Everyday field names are rewritten for you.
• Never loses a row. An address that cannot be verified still produces a row saying so, so the output lines up with the input.

Input

Paste a list of addresses and your own credentials. Everything else has a working default.

{
  "scope": "us",
  "addresses": [
    { "street": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA" },
    { "street": "210 King St", "zipcode": "94107" },
    "1 Infinite Loop, Cupertino CA 95014"
  ],
  "match": "strict",
  "candidates": 1,
  "features": ["component-analysis"],
  "maxResults": 100
}

For addresses outside the United States, set scope to international and give every address a country.

{
  "scope": "international",
  "country": "GBR",
  "addresses": [
    { "address1": "10 Downing St", "locality": "London", "postal_code": "SW1A 2AA" }
  ],
  "geocode": true
}

Example output

One row per verified candidate.

{
  "scope": "us",
  "verified": true,
  "inputIndex": 1,
  "inputSummary": "210 King St, 94107",
  "deliveryLine1": "210 KING ST",
  "lastLine": "SAN FRANCISCO CA 94107-1702",
  "deliveryPointBarcode": "941071702108",
  "primaryNumber": "210",
  "streetName": "KING",
  "streetSuffix": "ST",
  "cityName": "SAN FRANCISCO",
  "stateAbbreviation": "CA",
  "zipcode": "94107",
  "plus4Code": "1702",
  "recordType": "S",
  "zipType": "Standard",
  "countyName": "San Francisco",
  "countyFips": "06075",
  "carrierRoute": "C032",
  "congressionalDistrict": "11",
  "rdi": "Commercial",
  "latitude": 37.77597,
  "longitude": -122.39295,
  "precision": "Zip9",
  "timeZone": "Pacific",
  "utcOffset": -8,
  "dpvMatchCode": "Y",
  "dpvFootnotes": "AABB",
  "dpvCmra": "N",
  "dpvVacant": "N",
  "footnotes": "N#"
}

Frequently asked questions

What is an address verification API?

An address verification API takes an address as a person typed it and checks it against the authoritative postal database for that country. It returns the corrected, standardized form of the address, a flag saying whether mail can actually be delivered there, and the reason when it cannot. In the United States that authority is the USPS, and the specific check is called Delivery Point Validation.

What does the DPV match code mean?

The DPV match code is the USPS verdict on deliverability. Y means every part of the address, including the apartment or suite, was confirmed as a real delivery point. S means the street address is real but the secondary unit number is not, so mail may not reach the intended person. D means the street address is real but a required apartment number is missing entirely. N means the address was not confirmed. Anything other than Y is worth acting on before you post to it.

Can it verify addresses outside the United States?

Yes. Set the coverage option to international and the actor calls the provider's international service, which covers more than 240 countries and territories. Every international address must carry a country, given as a name or an ISO code such as GBR, DEU or JPN. The international service returns a verification status, an address precision level, and the address formatted the way that country's postal authority writes it.

Does it return latitude and longitude?

Yes. Every US result includes latitude, longitude and a precision level that tells you what the coordinates actually describe, from a ZIP code centroid up to a rooftop point on the building. For international addresses coordinates are an extra entitlement on most plans, so they are off by default and are turned on with the geocode option.

How do I tell a residential address from a business address?

The RDI field on every US result reports Residential or Commercial. This is the field shipping calculators need, because most carriers charge a residential delivery surcharge and quoting without it produces rates that are wrong at invoice time.

What is ZIP+4 and why does it matter?

ZIP+4 is the five digit ZIP code plus a four digit add-on that narrows delivery down to roughly one side of one city block, a single building, or a single floor. Presorted postage discounts require it, and it is the difference between a mailing that qualifies for bulk rates and one that does not.

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's auth ID and auth token, so you keep your own plan, your own rate limits and your own data agreement. Use a secret key pair rather than an embedded key, because embedded keys are locked to a website host and will not authenticate from a server.

What happens to an address that cannot be verified?

It is still written to the dataset, with verified set to false and a note explaining that the provider found no matching address. That is deliberate: for most people the whole point of running a check is finding the bad rows. Set skipUnverified to true if you only want the deliverable ones.

How much does a run cost?

Charging is per row. Every address the provider answered is charged, including addresses confirmed not to exist, because the provider bills that lookup either way. Addresses this actor refuses before sending, such as a row with no street line, are never charged. Set maxResults to cap what a run can spend.

Can one address return more than one result?

Yes. Raise candidates above one and an ambiguous input, such as a street name with no house number or an address that exists in two ZIP codes, returns every possibility rather than nothing. Each candidate is its own row and is charged as its own row.

Keyword map

address verification API, address validation API, USPS address verification, address standardization API, ZIP+4 lookup API, DPV delivery point validation, CASS address checking, international address verification, global address validation, address autocomplete data, residential delivery indicator, RDI lookup, address geocoding API, rooftop geocoding, county FIPS lookup, carrier route lookup, congressional district by address, bulk address cleaning, mailing list hygiene, deliverability checking