Validate Addresses

curl -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"
      }
    ]
  }'

const response = await fetch(
  "https://api.v2.dealmachine.com/v1/addresses/validate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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" },
      ],
    }),
  }
);

const { data, totals } = await response.json();

for (const item of data) {
  if (item.status === "valid") {
    console.log(`Deliverable: ${item.standardized_address}`);
  } else {
    console.log(`${item.status}: ${item.input.full_address || item.input.street}`);
    if (item.corrections?.length) {
      console.log(`  Corrections: ${item.corrections.join(", ")}`);
    }
  }
}

import requests

response = requests.post(
    "https://api.v2.dealmachine.com/v1/addresses/validate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "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"},
        ],
    },
)

body = response.json()
for item in body["data"]:
    if item["status"] == "valid":
        print(f"Deliverable: {item['standardized_address']}")
    else:
        addr = item["input"].get("full_address") or item["input"].get("street")
        print(f"{item['status']}: {addr}")

{
  "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
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "req_abc123def456",
    "details": {
      "issues": [
        {
          "path": "data[0]",
          "message": "Provide either full_address or street + city + state"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "request_id": "req_def456ghi789"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the specified time.",
    "request_id": "req_ghi789jkl012"
  }
}

POST

addresses

validate

curl -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"
      }
    ]
  }'

const response = await fetch(
  "https://api.v2.dealmachine.com/v1/addresses/validate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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" },
      ],
    }),
  }
);

const { data, totals } = await response.json();

for (const item of data) {
  if (item.status === "valid") {
    console.log(`Deliverable: ${item.standardized_address}`);
  } else {
    console.log(`${item.status}: ${item.input.full_address || item.input.street}`);
    if (item.corrections?.length) {
      console.log(`  Corrections: ${item.corrections.join(", ")}`);
    }
  }
}

import requests

response = requests.post(
    "https://api.v2.dealmachine.com/v1/addresses/validate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "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"},
        ],
    },
)

body = response.json()
for item in body["data"]:
    if item["status"] == "valid":
        print(f"Deliverable: {item['standardized_address']}")
    else:
        addr = item["input"].get("full_address") or item["input"].get("street")
        print(f"{item['status']}: {addr}")

{
  "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
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "req_abc123def456",
    "details": {
      "issues": [
        {
          "path": "data[0]",
          "message": "Provide either full_address or street + city + state"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "request_id": "req_def456ghi789"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the specified time.",
    "request_id": "req_ghi789jkl012"
  }
}

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

array

required

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

Show Address object properties

string

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

string

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

string

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

string

City name. Required when not using full_address.

string

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

string

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

curl -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"
      }
    ]
  }'

const response = await fetch(
  "https://api.v2.dealmachine.com/v1/addresses/validate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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" },
      ],
    }),
  }
);

const { data, totals } = await response.json();

for (const item of data) {
  if (item.status === "valid") {
    console.log(`Deliverable: ${item.standardized_address}`);
  } else {
    console.log(`${item.status}: ${item.input.full_address || item.input.street}`);
    if (item.corrections?.length) {
      console.log(`  Corrections: ${item.corrections.join(", ")}`);
    }
  }
}

import requests

response = requests.post(
    "https://api.v2.dealmachine.com/v1/addresses/validate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "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"},
        ],
    },
)

body = response.json()
for item in body["data"]:
    if item["status"] == "valid":
        print(f"Deliverable: {item['standardized_address']}")
    else:
        addr = item["input"].get("full_address") or item["input"].get("street")
        print(f"{item['status']}: {addr}")

{
  "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
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "req_abc123def456",
    "details": {
      "issues": [
        {
          "path": "data[0]",
          "message": "Provide either full_address or street + city + state"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "request_id": "req_def456ghi789"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the specified time.",
    "request_id": "req_ghi789jkl012"
  }
}

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.

Autocomplete Addresses List Locations

⌘I

Overview

Account

Filters

Fields

Properties

People

Exports

Lists

Enrichment

Phones

Activity

Addresses

Locations

Tasks

When to Use This

Body Parameters

Response Fields

Validation Statuses

Valid / Corrected Result

Delivery Types

Correction Codes

Invalid Result

Error Codes

Totals

Credits

Notes

​When to Use This

​Body Parameters

​Response Fields

​Validation Statuses

​Valid / Corrected Result

​Delivery Types

​Correction Codes

​Invalid Result

​Error Codes

​Totals

​Credits

​Notes

When to Use This

Body Parameters

Response Fields

Validation Statuses

Valid / Corrected Result

Delivery Types

Correction Codes

Invalid Result

Error Codes

Totals

Credits

Notes