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.

ShipEngine 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 or higher.

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.

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 response includes 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": []
  }
]

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

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: Unverified Status

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

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

Example: Warning Status

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

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

Example: Error Status

This address cannot be verified because the postal_code is incorrect.

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