SHshipengine
addresses

Validate An Address

Changed on

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

Response

The request was a success.

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

The possible address validation status values

Example response

[
  {
    "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"
    },
    "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"
    },
    "messages": [
      {
        "message": "Invalid Postal Code"
      }
    ]
  }
]

Changes

  • e4ae9b442f54Revision changes
    • 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

  • 5a15ef11fd60Revision changes
    • warning

      added the new file_not_found enum value to the //// response property for the response status

    • warning

      added the new file_not_found enum value to the //// response property for the response status

    • warning

      added the new funding_source_error enum value to the //// response property for the response status

    • warning

      added the new funding_source_error enum value to the //// response property for the response status

    • warning

      added the new funding_source_missing_configuration enum value to the //// response property for the response status

    • warning

      added the new funding_source_missing_configuration enum value to the //// response property for the response status

    • warning

      added the new funding_source_registration_in_progress enum value to the //// response property for the response status

    • warning

      added the new funding_source_registration_in_progress enum value to the //// response property for the response status

    • warning

      added the new insurance_failure enum value to the //// response property for the response status

    • warning

      added the new insurance_failure enum value to the //// response property for the response status

    • warning

      added the new service_not_determined enum value to the //// response property for the response status

    • warning

      added the new service_not_determined enum value to the //// response property for the response status

    • warning

      added the new shipping_rule_not_found enum value to the //// response property for the response status

    • warning

      added the new shipping_rule_not_found enum value to the //// response property for the response status