# US Address Verification API - USPS Deliverability and ZIP+4 (`nabeelbaghoor/us-address-verification-api`) Actor

Check whether a US address is really deliverable by USPS. Returns the corrected address, ZIP+4, delivery point barcode, DPV confirmation, vacancy and CMRA flags, residential or commercial type, county FIPS, carrier route and coordinates, plus a confidence score on every row.

- **URL**: https://apify.com/nabeelbaghoor/us-address-verification-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 address checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## US Address Verification API - USPS Deliverability and ZIP+4

Find out whether a US address is really deliverable before you post to it, and get back the corrected address with ZIP+4, DPV confirmation and a confidence score.

### What it does

- **Answers the actual question: will mail arrive?** Every row carries a deliverability verdict that separates a good address from one missing an apartment number, one with an apartment number that does not exist, and one that is simply not real.
- **Corrects and standardizes as it verifies.** Misspelled street names, missing directionals, wrong ZIP codes and abbreviated suffixes come back fixed and in USPS format.
- **Returns ZIP+4 and the delivery point barcode.** The four digit add-on and the 12 digit barcode that presorted postage discounts depend on.
- **Flags vacant addresses, CMRAs and PO boxes.** DPV analysis reports whether the address has been vacant for 90 days, whether it is a commercial mail receiving agency such as a mailbox rental, and whether it accepts only PO box mail.
- **Tells residential from commercial.** The address type field is what shipping rate logic needs, since carriers apply a residential surcharge that quotes are wrong without.
- **Scores its own confidence.** A numeric score and a high, medium or low level on every row, so a review queue can be sorted by how much a result should be trusted.
- **Adds county FIPS, carrier route and coordinates.** Latitude and longitude come back on the same call, so tax lookup and territory logic do not need a second provider.
- **Verifies twenty addresses per request.** Addresses given as components are batched automatically, so a large list costs far fewer HTTP round trips than one call per address.
- **Never loses a row.** An address that cannot be verified still produces a row saying why, so the output lines up with the input.

### Input

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

```json
{
  "addresses": [
    { "primary_line": "210 King St", "city": "San Francisco", "state": "CA", "zip_code": "94107" },
    { "primary_line": "1600 Amphitheatre Pkwy", "zip_code": "94043" },
    { "line1": "350 5th Ave", "town": "New York", "province": "NY", "zip": "10118" },
    "1 Infinite Loop, Cupertino CA 95014"
  ],
  "casing": "upper",
  "maxResults": 100
}
```

Each address needs a street line plus either a ZIP code or both a city and a state. A row with neither is refused before it is sent, so it costs nothing.

### Example output

One row per address.

```json
{
  "verified": true,
  "deliverability": "deliverable",
  "validAddress": true,
  "inputIndex": 0,
  "inputSummary": "210 King St, San Francisco, CA, 94107",
  "id": "us_ver_c7cb63d68f8d6",
  "primaryLine": "210 KING ST",
  "lastLine": "SAN FRANCISCO CA 94107-1702",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zipCode": "94107",
  "zipCodePlus4": "1702",
  "zipCodeType": "standard",
  "deliveryPointBarcode": "941071702108",
  "addressType": "commercial",
  "recordType": "street",
  "county": "SAN FRANCISCO",
  "countyFips": "06075",
  "carrierRoute": "C032",
  "carrierRouteType": "city_delivery",
  "latitude": 37.77597542841264,
  "longitude": -122.3929557343685,
  "dpvConfirmation": "Y",
  "dpvCmra": "N",
  "dpvVacant": "N",
  "dpvActive": "Y",
  "dpvFootnotes": ["AA", "BB"],
  "confidenceScore": 100,
  "confidenceLevel": "high"
}
```

### Frequently asked questions

#### What does the deliverability field actually mean?

It is a single verdict on whether USPS will deliver mail to the address. `deliverable` means yes. `deliverable_unnecessary_unit` means yes, but the apartment or suite number you supplied is not needed. `deliverable_incorrect_unit` means the building is real but the unit number probably is not, so mail may reach the building and not the person. `deliverable_missing_unit` means the building is real and a unit number is required but was not given. `undeliverable` means USPS will not deliver there at all.

#### What is DPV confirmation?

Delivery Point Validation is the USPS check that an address is a real, individual delivery point rather than merely a plausible one on a real street. `dpvConfirmation` of `Y` means every element including the secondary unit was confirmed. `S` means the street address is confirmed but the unit is not. `D` means a required unit number is missing. `N` means the address was not confirmed.

#### Can it tell me if an address is vacant?

Yes. `dpvVacant` is `Y` when USPS has recorded the address as unoccupied for 90 days or more. This is the field that catches customers who moved, and it is a common reason mail is returned even though the address itself is perfectly valid.

#### What is a CMRA and why would I care?

A commercial mail receiving agency is a private mailbox rental, the kind of address that looks like a suite number but is really a box at a shipping store. `dpvCmra` flags it. It matters for fraud screening, for identity verification, and for anyone whose terms require a real street address rather than a mail drop.

#### Does it return latitude and longitude?

Yes. Coordinates come back on the same verification call, alongside county, county FIPS code and carrier route, so a single run covers address checking, geocoding and tax jurisdiction lookup at once.

#### How many addresses does one request handle?

Twenty. Addresses supplied as components are batched twenty per request automatically, which is the provider's documented ceiling. Addresses supplied as a single string go one per request, because the bulk route does not accept them. Both produce identical rows, so you do not need to care which lane an address took.

#### Do I need my own API key?

Yes. This actor is bring your own key: it calls the verification API using your own account key, so you keep your own plan, your own rate limits and your own data agreement. Use a live key. A test key is accepted, but the provider answers it with placeholder data instead of checking the real address, and this actor warns you in the log when it sees one.

#### What is the confidence score?

A numeric score from 0 to 100 with a high, medium or low band, reflecting how strongly the provider believes the returned address matches what you sent. It is the field to sort by when a human has to review borderline results, because it separates a clean exact match from a correction that happened to be plausible.

#### What happens to an address that cannot be verified?

It is still written to the dataset. An address USPS rejects gets a row with its deliverability verdict; an address the provider refused outright gets a row with the provider's own reason. Set `skipUndeliverable` to true if you only want the good ones.

#### How much does a run cost?

Charging is per row. Every address the provider answered is charged, deliverable or not, because the provider bills that lookup either way. Rows refused before sending, such as a street line with no ZIP and no city and state, are never charged. Set `maxResults` to cap what a run can spend.

### Keyword map

US address verification API, USPS address validation, address deliverability check, DPV confirmation, delivery point validation, ZIP+4 lookup, delivery point barcode, CASS certified address checking, address standardization, vacant address detection, CMRA detection, residential vs commercial address, address type lookup, county FIPS by address, carrier route lookup, bulk address verification, mailing list cleaning, address geocoding, undeliverable mail prevention, direct mail data hygiene

# Actor input Schema

## `addresses` (type: `array`):

One object per address, using this provider's own field names: primary\_line, secondary\_line, urbanization, city, state, zip\_code and recipient. Everyday names are accepted too and rewritten for you, so line1, unit, town, province, zip and company all work. A plain string, or an object with a single address field, is treated as a whole address in one line. Each address needs a street line plus either a ZIP code or both a city and a state.

## `apiKey` (type: `string`):

Your own account's API key for this provider. Bring your own key: nothing is shared between runs and the key is never written to the dataset. A live key verifies real addresses; a test key returns placeholder data without checking anything, and this actor warns you when it sees one.

## `casing` (type: `string`):

How the corrected address lines are capitalised. Upper case is what USPS mailing standards expect and what automated mail sorting reads most reliably. Proper case is what you want if the address is going to be shown to a person or printed on a letter.

## `skipUndeliverable` (type: `boolean`):

Leave addresses USPS will not deliver to out of the dataset entirely. Off by default, because finding the undeliverable rows is usually the reason for running a check. They are charged either way, because the provider bills the lookup.

## `baseUrl` (type: `string`):

Overrides the host outright. Leave empty unless your account was issued a dedicated hostname.

## `maxResults` (type: `integer`):

Stop after this many rows. Rows are charged individually, so this is the ceiling on what a run can cost.

## `requestsPerMinute` (type: `integer`):

How fast to call the provider. Addresses given as components are sent twenty per request, so the default pace covers a much larger number of addresses per minute than it looks. Lower it if your plan has a tighter rate ceiling.

## Actor input object example

```json
{
  "addresses": [
    {
      "primary_line": "210 King St",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94107"
    },
    {
      "primary_line": "1600 Amphitheatre Pkwy",
      "zip_code": "94043"
    }
  ],
  "casing": "upper",
  "skipUndeliverable": false,
  "maxResults": 100,
  "requestsPerMinute": 240
}
```

# Actor output Schema

## `addresses` (type: `string`):

One row per address, alongside the input it was matched from.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        {
            "primary_line": "210 King St",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107"
        },
        {
            "primary_line": "1600 Amphitheatre Pkwy",
            "zip_code": "94043"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/us-address-verification-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "addresses": [
        {
            "primary_line": "210 King St",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
        },
        {
            "primary_line": "1600 Amphitheatre Pkwy",
            "zip_code": "94043",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/us-address-verification-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    {
      "primary_line": "210 King St",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "94107"
    },
    {
      "primary_line": "1600 Amphitheatre Pkwy",
      "zip_code": "94043"
    }
  ]
}' |
apify call nabeelbaghoor/us-address-verification-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/us-address-verification-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/D2HpHhYxTAJjp7nA3/builds/3BbX21jzqUtgipxPh/openapi.json