> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

## 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](/api-reference/enrichment/enrich-by-address) to improve match rates

## Body Parameters

<ParamField body="data" type="array" required>
  Array of address objects to validate (max 1,000).

  <Expandable title="Address object properties">
    <ParamField body="full_address" type="string">
      Complete address string (e.g., `"1200 Barton Springs Rd, Austin, TX 78704"`). Use this **or** the structured fields below — not both.
    </ParamField>

    <ParamField body="street" type="string">
      Street address line (e.g., `"1200 Barton Springs Rd"`). Required when not using `full_address`.
    </ParamField>

    <ParamField body="unit" type="string">
      Unit, apartment, or suite number (e.g., `"Apt 4B"`, `"Suite 200"`). Optional.
    </ParamField>

    <ParamField body="city" type="string">
      City name. Required when not using `full_address`.
    </ParamField>

    <ParamField body="state" type="string">
      Two-letter state abbreviation. Required when not using `full_address`.
    </ParamField>

    <ParamField body="zip" type="string">
      5-digit ZIP code. Optional when using structured fields, but improves validation accuracy.
    </ParamField>
  </Expandable>
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```

  ```typescript Node.js theme={null}
  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(", ")}`);
      }
    }
  }
  ```

  ```python Python theme={null}
  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}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "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"
          }
        ]
      }
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "invalid_api_key",
      "message": "The provided API key is invalid",
      "request_id": "req_def456ghi789"
    }
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "Too many requests. Please retry after the specified time.",
      "request_id": "req_ghi789jkl012"
    }
  }
  ```
</ResponseExample>

## 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](/concepts/credits) 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](/concepts/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](/api-reference/properties/search-properties) and [Search People](/api-reference/people/search-people).