---
title: "Validate An Address"
method: POST
path: "/v1/addresses/validate"
tags: ["addresses"]
---

# Validate An Address

`POST /v1/addresses/validate`

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.

## Request body

- AddressToValidate[] — An address validation request body
  - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
  - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
  - `email` string, nullable — Email for the address owner.
  - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
  - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
  - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
  - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
  - `city_locality` string — The name of the city or locality
  - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
  - `postal_code` string — postal code
  - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
  - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.

## Response `200`

The request was a success.

- AddressValidationResult[] — An address validation response body
  - `status` 'unverified' | 'verified' | 'warning' | 'error', required — The possible address validation status values
  - `original_address` Address, required — A complete or partial mailing address.
    - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
    - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
    - `email` string, nullable — Email for the address owner.
    - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
    - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
    - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
    - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
    - `city_locality` string — The name of the city or locality
    - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
    - `postal_code` string — postal code
    - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.
  - `matched_address` Address, required — A complete or partial mailing address.
    - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
    - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
    - `email` string, nullable — Email for the address owner.
    - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
    - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
    - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
    - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
    - `city_locality` string — The name of the city or locality
    - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
    - `postal_code` string — postal code
    - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.
  - `messages` ResponseMessage[], required — The list of messages that were generated during the address validation request.
    - `code` 'a1000' | 'a1001' | 'a1002' | 'a1003' | 'a1004' | 'a1005' | 'a1006' | 'a1007' | 'a1008' | 'r1000' | 'r1001' | 'r1002' | 'r1003', required — The error codes that can be returned by the address validation API
    - `message` string, required — Message explaining the address validation error
    - `type` 'error' | 'warning' | 'info', required — The different types of messages that can be returned by the address validation API
    - `detail_code` 'unsupported_country' | 'non_supported_country' | 'minimum_postal_code_verification_failed' | 'street_does_not_match_unique_street_name' | 'multiple_directionals' | 'multiple_matches' | 'suite_not_valid' | 'suite_missing' | 'incompatible_paired_labels' | 'invalid_house_number' | 'missing_house_number' | 'invalid_box_number' | 'invalid_charge_event' | 'missing_box_number' | 'missing_cmra_or_private_mail_box_number' | 'suite_has_no_secondaries' | 'postal_code_changed_or_added' | 'state_province_changed_or_added' | 'city_locality_changed_or_added' | 'urbanization_changed' | 'street_name_spelling_changed_or_added' | 'street_name_type_changed_or_added' | 'street_direction_changed_or_added' | 'suite_type_changed_or_added' | 'suite_unit_number_changed_or_added' | 'double_dependent_locality_changed_or_added' | 'subadministrative_area_changed_or_added' | 'subnational_area_changed_or_added' | 'po_box_changed_or_added' | 'premise_type_changed_or_added' | 'house_number_changed' | 'organization_changed_or_added' | 'partially_verified_to_state_level' | 'partially_verified_to_city_level' | 'partially_verified_to_street_level' | 'partially_verified_to_premise_level' | 'verified_to_state_level' | 'verified_to_city_level' | 'verified_to_street_level' | 'verified_to_premise_level' | 'verified_to_suite_level' | 'coded_to_street_lavel' | 'coded_to_neighborhood_level' | 'coded_to_community_level' | 'coded_to_state_level' | 'coded_to_rooftop_level' | 'coded_to_rooftop_interpolation_level' | 'name_max_length_exceeded' | 'phone_max_length_exceeded' | 'company_name_max_length_exceeded' | 'line1_min_max_length' | 'line2_max_length_exceeded' | 'line3_max_length_exceeded' | 'city_locality_max_length_exceeded' | 'state_province_max_length_exceeded' | 'invalid_postal_code' | 'country_invalid_length' | 'address_not_found', required — The detailed error codes that can be returned by the address validation API

## Other responses

- `400` — The request contained errors.
- `500` — An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers.

---

[API](https://skmtc.net/shipengine/apis/shipengine-api.md) · [All operations](https://skmtc.net/shipengine/apis/shipengine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipengine/shipengine-api/revisions/6af91511d87e/schema)