addresses

Validate an address

Changed on Oct 22, 2026

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.

post/v1/addresses/validate

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/addresses/validate
Auth: API key in header API-Key

Request body

namestring

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

phonestring

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

emailstring nullable

Email for the address owner.

company_namestring nullable

If this is a business address, then the company name should be specified here.

address_line1string

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_line2string nullable

The second line of the street address. For some addresses, this line may not be needed.

address_line3string nullable

The third line of the street address. For some addresses, this line may not be needed.

city_localitystring

The name of the city or locality

state_provincestring

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

postal_codestring

postal code

country_codestring

A two-letter ISO 3166-1 country code

address_residential_indicator'unknown' | 'yes' | 'no'

Indicates whether an address is residential.

Example request

[
  {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
  }
]

Response

The request was a success.

status'unverified' | 'verified' | 'warning' | 'error' required

The possible address validation status values

Example response

[
  {
    "status": "verified",
    "original_address": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "address_residential_indicator": "no"
    },
    "matched_address": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "address_residential_indicator": "no"
    },
    "messages": [
      {
        "message": "Invalid Postal Code"
      }
    ]
  }
]

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the /// request property's minLength was increased from 0 to 1
- breaking
  the /// request property type changed from no type to string
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the ///// response's property type changed from no type to string for status
- breaking
  the // response's property type changed from no type to string for status
- warning
  removed from the /// request property allOf list
- warning
  added the new error enum value to the // response property for the response status
- warning
  added the new unverified enum value to the // response property for the response status
- warning
  added the new verified enum value to the // response property for the response status
- warning
  added the new warning enum value to the // response property for the response status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added to the // response property allOf list for the response status
- info
  removed from the // response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the // response property allOf list for the response status
- info
  removed from the ///// response property allOf list for the response status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (4 revisions)