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.

Example

POST /v1/addresses/validate

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

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

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

statusdescription
verifiedAddress was successfully verified.
unverifiedAddress validation was not validated against the database because pre-validation failed.
warningThe address was validated, but the address should be double checked.
errorThe 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"
}
]