v1

latestOpenAPI 3.1.02026-07-1270243932.3 KB

Addresses

Validate an address

Validates an existing address using an object ID

get/addresses/{AddressId}/validate

Path parameters

AddressIdstring required

Object ID of the address

Headers

SHIPPO-API-VERSIONstring

Example:2018-02-08

Optional string used to pick a non-default API version to use. See our <a href="https://docs.goshippo.com/docs/api_concepts/apiversioning/">API version</a> guide.

Response

Address

namestring

required for purchase<br> First and Last Name of the addressee

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Either company or name required; No length validation (first 35 chars printed on label)

companystring

Company Name

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Max 35 characters; Either company or name required

street1string

required for purchase<br> First street line. Usually street number and street name (except for DHL Germany, see street_no).

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	At least one street line required; Max 35 characters per line

street2string

Second street line.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	At least one street line required; Max 35 characters per line

street3string

Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	At least one street line required; Max 35 characters per line

street_nostring

Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.

citystring

required for purchase<br> Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Required; Max 35 characters

statestring

required for purchase for some countries<br> State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Required if country requires state; Max 2 characters for US, CA, PR

zipstring

required for purchase<br> Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Max 10 characters

countrystring required

ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like US or DE. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements" target="_blank">guide</a> for a list of country codes. Sending a country is always required.

phonestring

Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Required; Min 1, max 15 characters
USPS	Sender phone required for shipments during label purchase; Min 8, max 15 digits

emailstring

E-mail address of the contact person, RFC3696/5321-compliant.

Carrier-Specific Constraints:

Carrier	Constraints
FedEx	Max 80 characters
USPS	Sender email required for shipments during label purchase

is_residentialboolean

metadatastring

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

is_completeboolean

Complete addresses contain all required values.<br><br>Incomplete addresses have failed one or multiple validations.<br>Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.

object_createdstring date-time

Date and time of Address creation.

object_idstring

Unique identifier of the given Address object. This ID is required to create a Shipment object.

object_ownerstring

Username of the user who created the Address object.

object_updatedstring date-time

Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.

testboolean

Indicates whether the object has been created in test mode.

Example response

{
  "name": "Shwan Ippotle",
  "company": "Shippo",
  "street1": "215 Clayton St.",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94117",
  "country": "US",
  "phone": "+1 555 341 9393",
  "email": "shippotle@shippo.com",
  "is_residential": true,
  "metadata": "Customer ID 123456",
  "is_complete": true,
  "object_created": "2014-07-09T02:19:13.174Z",
  "object_id": "d799c2679e644279b59fe661ac8fa488",
  "object_owner": "shippotle@shippo.com",
  "object_updated": "2014-07-09T02:19:13.174Z",
  "validation_results": {
    "messages": [
      {
        "code": "Unknown Street",
        "source": "Shippo Address Validator",
        "text": "City, State and ZIP Code are valid, but street address is not a match.",
        "type": "address_warning"
      }
    ]
  }
}