# Validate an Address

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipStation API cross references multiple databases to validate *addresses* and identify potential deliverability issues.

ShipStation API supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.

## Requirements

* The address validation endpoint is available to accounts in the [Advanced plan](https://help.shipengine.com/hc/en-us/articles/19326509952027) or higher.


> **TIP:**
### Validate Addresses on the Free Plan
If you are on the [Free plan](https://help.shipengine.com/hc/en-us/articles/19326486755867), you can instead use the `validate_address` property in the [Create Label](/apis/shipengine/docs/reference/create-label) or [Get Rate](/apis/shipengine/docs/rates/estimate) calls to validate addresses. When validating with one of these methods, the call must include the `validate_address` property and specify either `validate_only` or `validate_and_clean`.


## Example Request & Response

**POST /v1/addresses/validate**

This is an example of a full request to the address verification service. The JSON body can validate up to 250 addresses per request.


```http
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]
```

**Example Response**

The response includes every address sent to the Address Validator, in the order it was received.


```json
[
  {
    "status": "verified",
    "original_address": {
      "name": null,
      "phone": null,
      "company_name": null,
      "address_line1": "525 S Winchester Blvd",
      "address_line2": null,
      "address_line3": null,
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "unknown"
    },
    "matched_address": {
      "name": null,
      "phone": null,
      "company_name": null,
      "address_line1": "525 S WINCHESTER BLVD",
      "address_line2": "",
      "address_line3": null,
      "city_locality": "SAN JOSE",
      "state_province": "CA",
      "postal_code": "95128-2537",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "messages": []
  }
]
```

## Response Statuses

The `status` field in the response can have one of the following four statuses:

| status | description |
|  --- | --- |
| `verified` | Address was successfully verified. |
| `unverified` | Address was not verified against the database because pre-validation failed. |
| `warning` | The address was validated, but could have formatting issues and should be double checked. |
| `error` | The address could not be validated with any degree of certainty against the database. |


### Example: Verified Status


```http
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]
```

### Example: Unverified Status

This issue is with the `country_code` value of "USA" rather than the approved 2-charater ISO country code "US".


```http
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "USA"
  }
]
```

### Example: Warning Status

This issue is with the entire address, while correct, being contained in the `address_line1` field.


```http
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "Studio Tour Drive, Leavesden WD25 7LR, UK",
    "country_code": "GB"
  }
]
```

### Example: Error Status

This address cannot be verified because the `postal_code` is incorrect.


```http
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "78756",
    "country_code": "US"
  }
]
```