Skip to main content
POST
/
addresses
cURL
curl https://api.goshippo.com/addresses/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -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@shippo.com"\
  -d is_residential=True\
  -d metadata="Customer ID 123456"
{
  "country": "US",
  "name": "Shwan Ippotle",
  "company": "Shippo",
  "street1": "215 Clayton St.",
  "street2": "<string>",
  "street3": "",
  "street_no": "",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94117",
  "phone": "+1 555 341 9393",
  "email": "shippotle@shippo.com",
  "is_residential": true,
  "metadata": "Customer ID 123456",
  "is_complete": true,
  "latitude": 123,
  "longitude": 123,
  "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": {
    "is_valid": false,
    "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"
      }
    ]
  },
  "test": false
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Address details.

Address represents the address as retrieved from the database

​
country
string
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 guide for a list of country codes. Sending a country is always required.

Example:

"US"

​
name
string

required for purchase
First and Last Name of the addressee

Carrier-Specific Constraints:

CarrierConstraints
FedExEither company or name required; No length validation (first 35 chars printed on label)
Maximum string length: 100
Example:

"Shwan Ippotle"

​
company
string

Company Name

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 35 characters; Either company or name required
Maximum string length: 100
Example:

"Shippo"

​
street1
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 121
Example:

"215 Clayton St."

​
street2
string

Second street line.

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 100
​
street3
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 100
Example:

""

​
street_no
string

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

Example:

""

​
city
string

required for purchase
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:

CarrierConstraints
FedExRequired; Max 35 characters
Maximum string length: 100
Example:

"San Francisco"

​
state
string

required for purchase for some countries
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:

CarrierConstraints
FedExRequired if country requires state; Max 2 characters for US, CA, PR
Maximum string length: 100
Example:

"CA"

​
zip
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 10 characters
Maximum string length: 20
Example:

"94117"

​
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.

Carrier-Specific Constraints:

CarrierConstraints
FedExRequired; Min 1, max 15 characters
USPSSender phone required for shipments during label purchase; Min 8, max 15 digits
Maximum string length: 50
Example:

"+1 555 341 9393"

​
email
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 80 characters
USPSSender email required for shipments during label purchase
Maximum string length: 254
Example:

"shippotle@shippo.com"

​
is_residential
boolean
Example:

true

​
metadata
string

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

Maximum string length: 100
Example:

"Customer ID 123456"

​
validate
boolean

Set to true to validate Address object.

Example:

true

Response

Address

Address represents the address as retrieved from the database

​
country
string
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 guide for a list of country codes. Sending a country is always required.

Example:

"US"

​
name
string

required for purchase
First and Last Name of the addressee

Carrier-Specific Constraints:

CarrierConstraints
FedExEither company or name required; No length validation (first 35 chars printed on label)
Maximum string length: 100
Example:

"Shwan Ippotle"

​
company
string

Company Name

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 35 characters; Either company or name required
Maximum string length: 100
Example:

"Shippo"

​
street1
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 121
Example:

"215 Clayton St."

​
street2
string

Second street line.

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 100
​
street3
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExAt least one street line required; Max 35 characters per line
Maximum string length: 100
Example:

""

​
street_no
string

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

Example:

""

​
city
string

required for purchase
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:

CarrierConstraints
FedExRequired; Max 35 characters
Maximum string length: 100
Example:

"San Francisco"

​
state
string

required for purchase for some countries
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:

CarrierConstraints
FedExRequired if country requires state; Max 2 characters for US, CA, PR
Maximum string length: 100
Example:

"CA"

​
zip
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 10 characters
Maximum string length: 20
Example:

"94117"

​
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.

Carrier-Specific Constraints:

CarrierConstraints
FedExRequired; Min 1, max 15 characters
USPSSender phone required for shipments during label purchase; Min 8, max 15 digits
Maximum string length: 50
Example:

"+1 555 341 9393"

​
email
string

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

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 80 characters
USPSSender email required for shipments during label purchase
Maximum string length: 254
Example:

"shippotle@shippo.com"

​
is_residential
boolean
Example:

true

​
metadata
string

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

Maximum string length: 100
Example:

"Customer ID 123456"

​
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.

Example:

true

​
latitude

Latitude of address

​
longitude

Longitude of address

​
object_created
string<date-time>

Date and time of Address creation.

Example:

"2014-07-09T02:19:13.174Z"

​
object_id
string

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

Example:

"d799c2679e644279b59fe661ac8fa488"

​
object_owner
string

Username of the user who created the Address object.

Example:

"shippotle@shippo.com"

​
object_updated
string<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.

Example:

"2014-07-09T02:19:13.174Z"

​
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).

​
test
boolean

Indicates whether the object has been created in test mode.

Example:

false