Addresses¶

The Address Object¶

Attribute	Data Type	Description
is_complete	boolean	Complete addresses contain all required values. Incomplete addresses have failed one or multiple validations. Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.
object_created	datetime	Date and time of Address creation.
object_updated	datetime	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.
object_id	string	Unique identifier of the given Address object. This ID is required to create a Shipment object.
object owner	string	Username of the user who created the Address object.
name	string	First and Last Nameo of the addressee
company	string	Company Name
street1	string	First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
street_no	string	Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
street2	string	Second street line, 35 character limit.
street3	string	Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.
city	string	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.
zip	string	Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates.
state	string	State values are only required for shipments from the United States and Canada (most carriers only accept two-character state abbreviations). However, to receive more accurate quotes, passing it is generally recommended.
country	ISO 2 country code	Example: 'US' or 'DE'. All accepted values can be found on the Official ISO Website. Sending a country is always required.
phone	string	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.
email	email	E-mail address of the contact person, RFC3696/5321-compliant.
is_residential	nullable boolean	Indicates whether the address provided is a residential address or not.
validate	nullable boolean	Set to true to validate Address object.
metadata	string	A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
test	bool	Indicates whether the object has been created in test mode.
validation_results	object	object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are is_valid (boolean) and messages (array).

`POST` Create a New Address¶

A POST to the /addresses resource to allow your application to create a new address object.

/addresses/

BODY PARAMETERS

Parameter	Required/Optional	Data Type	Description
name	optional	string	name of purchaser
company	optional	string	name of company
street1	required	string	street name
street_no	optional	string	building number
street2	optional	string	street name (secondary)
city	required	string	name of the city
zip	required	string	zip (USA) or postal (Canada) code
state	required	string	name of state (USA) or province (Canada)
country	required	ISO 2 country code	name of country
phone	optional	string	phone number
email	optional	email	email address contact
is_residential	optional	boolean	is residential?
validate	optional	boolean	for potential validation
metadata	optional	string	any metadata to pass along

EXAMPLE REQUEST (Create a New Address):

curl https://api.goshippo.com/addresses/ 
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"
    -d name="Shawn Ippotle" \
    -d company="Shippo" \
    -d street1="215 Clayton St." \
    -d street2="" \
    -d city="San Francisco" \
    -d state="CA" \
    -d zip=94117 \
    -d country="US" \
    -d phone="+1 555 341 9393" \
    -d email="shippotle@goshippo.com"\
    -d is_residential=True\
    -d metadata="Customer ID 123456"

EXAMPLE RESPONSE (from Create a New Address):

{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street1":"215 Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}

`GET` Retrieve an Address¶

A GET to the /addresses resource to allow your application to retrieve an existing address by object ID.

/addresses/{address object id}

PATH PARAMETERS

Parameter	Required/Optional	Data Type	Description
Address Object ID	required	string	address object id

EXAMPLE REQUEST (Retrieve an Address)

curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \
  -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from Retrieve an Address):

{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@goshippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "street1":"215 Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"shippotle@goshippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456",
   "test": true
}

`GET` Validate an Address¶

A GET to the /address resource to allow your application to validate an address object.

/addresses/{address object id}/validate/

PATH PARAMETERS

Parameter	Required/Optional	Data Type	Description
Address Object ID	required	string	address object id

EXAMPLE REQUEST (Validate an Address)

curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/ \
  -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from Validate an Address)

{
    "is_complete": false,
    "object_created": "2015-03-30T23:47:11.574Z",
    "object_updated": "2015-03-30T23:47:11.596Z", 
    "object_id": "67183b2e81e9421f894bfbcdc4236b16", 
    "object_owner": "shippotle@goshippo.com",
    "name": "Shawn Ippotle", 
    "company": "Shippo", 
    "street_no": "", 
    "street1": "215 CLAYTOON ST.", 
    "street2": "", 
    "city": "SAN FRANCISCO", 
    "state": "CA", 
    "zip": "94107", 
    "country": "US", 
    "phone": "", 
    "email": "shippotle@goshippo.com", 
    "is_residential": null,
    "metadata": "",
    "test": true,
    "validation_results": {
        "is_valid": false,
        "messages": [
            {
                "source": "USPS",
                "code": "Unknown Street",
                "text": "City, State and ZIP Code are valid, but street address is not a match."
            }
        ]
    }
}

`GET` List All Addresses¶

A GET to the /address resource to allow your application to list all addresses.

/addresses/

EXAMPLE REQUEST (List All Addresses)

curl https://api.goshippo.com/addresses/ \
  -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from List All Addresses)

{
   "next":null,
   "previous":null,
   "results":[
      {
         "is_complete": true,
         "object_created":"2014-07-16T23:20:31.089Z",
         "object_updated":"2014-07-16T23:20:31.089Z",
         "object_id":"747207de2ba64443b645d08388d0309c",
         "object_owner":"shippotle@goshippo.com",
         "validation_results": {},
         "name":"Shawn Ippotle",
         "street1":"215 Clayton St.",
         "street2":"",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94117",
         "country":"US",
         "phone":"15553419393",
         "email":"shippotle@goshippo.com",
         "is_residential":true,
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}

Addresses¶

The Address Object¶

POST Create a New Address¶

GET Retrieve an Address¶

GET Validate an Address¶

GET List All Addresses¶

`POST` Create a New Address¶

`GET` Retrieve an Address¶

`GET` Validate an Address¶

`GET` List All Addresses¶