Validate an Address

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

Address Validation on ShipEngine's Free Plan

If you are on ShipEngine's Free Plan, you must use the Create Label or Get Rate call to access the address validation functionality.

One of the following properities must be specified in the call:

"validate_address": "validate_and_clean"
"validate_address": "validate_only"

Example

POST /v1/addresses/validate

For ShipEngine's Advance and above plans, this is a full request you can make to the address verification service. The JSON body can take up to 250 addresses to validate per request.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 Address Validation Response is provided for every address sent to the Address Validator, in the order it was received.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
  {
    "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": []
  }
]

Address Status Meanings

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

Samples

Verified Status

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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"
  }
]

Unverified Status

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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"
  }
]

Warning Status

1
2
3
4
5
6
7
8
9
10
11
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"
  }
]

Error Status

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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"
  }
]