Validate Addresses

Validate and standardize US addresses using USPS address data. Each item in the data array can use either a single full_address string or structured components (street, unit, city, state, zip).

Returns USPS-standardized versions of each submitted address along with a validation status indicating whether the address is deliverable.

Each request accepts up to 1,000 items in the data array. The response returns every submitted item with a status indicating the validation result.

When to Use This

Before mailing — verify addresses are deliverable so you don't waste postage
Data cleanup — standardize addresses in your CRM or spreadsheet before importing
Before enrichment — validate addresses before passing them to Enrich by Address to improve match rates

Body Parameters

body dataarrayrequired

Array of address objects to validate (max 1,000).

Address object properties

body full_addressstring

Complete address string (e.g., "1200 Barton Springs Rd, Austin, TX 78704"). Use this or the structured fields below — not both.

body streetstring

Street address line (e.g., "1200 Barton Springs Rd"). Required when not using full_address.

body unitstring

Unit, apartment, or suite number (e.g., "Apt 4B", "Suite 200"). Optional.

body citystring

City name. Required when not using full_address.

body statestring

Two-letter state abbreviation. Required when not using full_address.

body zipstring

5-digit ZIP code. Optional when using structured fields, but improves validation accuracy.

Response Fields

The response contains a data array and a totals object. There is no pagination — all submitted items are returned in a single response.

Validation Statuses

Status	Description
`valid`	The address exactly matched a USPS deliverable address. No corrections were needed.
`corrected`	The address was found but USPS made corrections (e.g., standardized abbreviations, added ZIP+4). The `corrections` array describes what changed.
`invalid`	The address could not be validated. See the `error` object for details.

Valid / Corrected Result

When status is valid or corrected, the result contains the USPS-standardized address:

Field	Type	Description
`input`	object	Echo of the original input object
`status`	string	`"valid"` or `"corrected"`
`standardized_address`	string	Full USPS-standardized address string
`street`	string	Standardized street line
`unit`	string \| null	Standardized unit/apartment, or `null` if none
`city`	string	Standardized city name
`state`	string	Two-letter state abbreviation
`zip`	string	5-digit ZIP code
`zip4`	string	ZIP+4 extension
`county`	string	County name
`fips`	string	5-digit FIPS county code
`delivery_type`	string	USPS delivery type (see below)
`vacant`	boolean	Whether USPS considers this address vacant
`corrections`	string[]	List of corrections applied. Empty array for `valid` results.

Delivery Types

Type	Description
`street`	Standard street delivery
`highrise`	Apartment or high-rise building
`po_box`	Post office box
`rural_route`	Rural route delivery
`general_delivery`	General delivery (held at post office)

Correction Codes

When status is corrected, the corrections array describes what was changed:

Code	Description
`zip_corrected`	ZIP code was corrected
`city_corrected`	City name was corrected or standardized
`state_corrected`	State was corrected
`street_standardized`	Street name or suffix was standardized (e.g., "Street" to "ST")
`unit_designator_standardized`	Unit designator was standardized (e.g., "Apartment" to "APT")
`directional_standardized`	Street directional was standardized (e.g., "South" to "S")
`zip4_added`	ZIP+4 was appended

Invalid Result

Field	Type	Description
`input`	object	Echo of the original input object
`status`	string	`"invalid"`
`error`	object	Structured error with `code` and `reason`

Error Codes

Code	Description
`address_not_found`	The address does not exist in the USPS database
`insufficient_address`	Not enough information to identify a specific address
`multiple_matches`	The address matched multiple deliverable locations — add a unit number to disambiguate
`invalid_state`	The state abbreviation is not valid
`invalid_zip`	The ZIP code is not valid or does not match the city/state

Totals

Field	Type	Description
`submitted`	integer	Number of items in the request `data` array
`valid`	integer	Number of addresses that matched exactly
`corrected`	integer	Number of addresses that matched with corrections
`invalid`	integer	Number of addresses that could not be validated

Credits

This endpoint consumes 1 credit per validated address (addresses with status of valid or corrected). Invalid addresses are free. Credits are deduplicated within your billing period — validating the same address again is free.

Every response includes a credits object with a full breakdown of what was charged. See Credits for details.

Notes

Each item must include either full_address or the combination of street + city + state. Including unit and zip with structured fields is optional but improves accuracy.
Items are validated independently — one invalid address does not affect others.
The input object is always echoed back so you can correlate results with your input data.
Standardized addresses use USPS formatting conventions: uppercase letters, standard abbreviations (ST, AVE, BLVD), and directional abbreviations (N, S, E, W).
The fips code in valid/corrected results can be used directly as a county location code in Search Properties and Search People.

Request example

1234567891011121314151617181920curl -X POST "https://api.v2.dealmachine.com/v1/addresses/validate" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "full_address": "1200 Barton Springs Rd, Austin, TX 78704"
      },
      {
        "street": "4500 S Lamar Blvd",
        "unit": "Apt 4B",
        "city": "Austin",
        "state": "TX",
        "zip": "78745"
      },
      {
        "full_address": "123 Fake Street, Nowhere, ZZ 00000"
      }
    ]
  }'

Response example

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566{
  "data": [
    {
      "input": {
        "full_address": "1200 Barton Springs Rd, Austin, TX 78704"
      },
      "status": "valid",
      "standardized_address": "1200 BARTON SPRINGS RD, AUSTIN, TX 78704-1227",
      "street": "1200 BARTON SPRINGS RD",
      "unit": null,
      "city": "AUSTIN",
      "state": "TX",
      "zip": "78704",
      "zip4": "1227",
      "county": "Travis",
      "fips": "48453",
      "delivery_type": "street",
      "vacant": false,
      "corrections": []
    },
    {
      "input": {
        "street": "4500 S Lamar Blvd",
        "unit": "Apt 4B",
        "city": "Austin",
        "state": "TX",
        "zip": "78745"
      },
      "status": "corrected",
      "standardized_address": "4500 S LAMAR BLVD APT 4B, AUSTIN, TX 78745-1234",
      "street": "4500 S LAMAR BLVD",
      "unit": "APT 4B",
      "city": "AUSTIN",
      "state": "TX",
      "zip": "78745",
      "zip4": "1234",
      "county": "Travis",
      "fips": "48453",
      "delivery_type": "highrise",
      "vacant": false,
      "corrections": ["unit_designator_standardized"]
    },
    {
      "input": {
        "full_address": "123 Fake Street, Nowhere, ZZ 00000"
      },
      "status": "invalid",
      "error": {
        "code": "address_not_found",
        "reason": "The address could not be found in the USPS database"
      }
    }
  ],
  "totals": {
    "submitted": 3,
    "valid": 1,
    "corrected": 1,
    "invalid": 1
  },
  "credits": {
    "used": 2,
    "properties": 2,
    "people": 0,
    "deduplicated": 0
  }
}