Validate Address

Beta
PUT/v1/core/addresses/actions/validate

This endpoint is idempotent. Learn more

Checks an address against an address validation service and returns a standardized version of it.

Nothing is created or modified. Use this before creating or updating an address to confirm it is complete and to pick up corrected values. When the service can standardize the address, formatted_address and components carry the corrected values, and validation_messages explains anything that was inferred, replaced, or could not be confirmed.

address_line_1string

First line of the street address.

address_line_2optional string

Second line of the street address.

citystring

City or locality.

statestring

State or administrative area.

postal_codestring

Postal or ZIP code.

countrystring

Two-letter country code, such as US.

A full country name such as United States is recognized for a handful of common countries; send the two-letter code for anywhere else.

objectstringenumValues:validated_address

Resource type identifier.

statusstringenumValues:validinvalid

Whether the address was confirmed as complete and specific enough to ship to.

  • valid: nothing required was missing and the address resolved to a specific building or block.
  • invalid: required components were missing, or the address only resolved to a street or a wider area.

When the status is invalid, read validation_messages and compare components against what you submitted to see what to correct.

formatted_addressstringnullable

Formatted, single-line address as standardized by the validation service.

The validation service may omit this regardless of status, so it can be absent even for a valid address.

componentsaddress_componentsnullable

Standardized, parsed address components returned by the validation service.

The validation service may omit this regardless of status, so it can be absent even for a valid address.

objectstringenumValues:address_components

Resource type identifier.

address_line_1string

First line of the street address.

address_line_2stringnullable

Second line of the street address.

citystring

City or locality.

statestring

State or administrative area.

postal_codestring

Postal or ZIP code.

countrystring

Country name or code.

country_codestring

Two-letter country code.

validation_messagesarray of string

Human-readable messages describing issues found during validation.

May be non-empty even when status is valid, for example when components were inferred or replaced with standardized values. Empty when no issues were reported.

Responses

200

Successful response for Validate Address