Retrieve a single address

Address Book

Store, retrieve, modify, and delete your address book contacts

Operations

Retrieve a single address

Request

Returns an existing address using an object ID

Security

Shippo_Token

Path

address_idstring(Address Id)required

curl -i -X GET \
'https://api.goshippo.com/v2/addresses/{address_id}' \
-H 'Authorization: ShippoToken <API_TOKEN>'

Responses

Successful Response

Bodyapplication/json

idstring(Id)required

Example: "e9f1f6fd20f84982afe471ff06c5a80f"

addressobject(Address)required

updated_atstring(date-time)(Updated At)required

created_atstring(date-time)(Created At)required

Response

application/json

{
  "id": "e9f1f6fd20f84982afe471ff06c5a80f",
  "address": {
    "name": "Wilson",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "organization": "Shippo",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Update an address

Request

Updates values in an existing address

Security

Shippo_Token

Path

address_idstring(Address Id)required

Bodyapplication/jsonrequired

namestring(Name)<= 64 charactersrequired

The name of the addressee

Example: "Wilson"

organizationOrganization (string) or Organization (null)(Organization)

The organization of the addressee

Example: "Shippo"

Any of:

The organization of the addressee

<= 100 characters

string(Organization)<= 100 characters

emailEmail (string) or Email (null)(Email)

The email of the addressee

Example: "user@shippo.com"

Any of:

The email of the addressee

[ 5 .. 128 ] characters

string(email)(Email)[ 5 .. 128 ] characters

phonePhone (string) or Phone (null)(Phone)

The phone number of the addressee

Example: "+1-4155550132"

Any of:

The phone number of the addressee

[ 3 .. 32 ] characters

string(Phone)[ 3 .. 32 ] characters

address_line_1string(Address Line 1)[ 1 .. 100 ] charactersrequired

The first line of the address

Example: "731 Market Street"

address_line_2Address Line 2 (string) or Address Line 2 (null)(Address Line 2)

The second line of the address

Example: "#200"

Any of:

The second line of the address

<= 50 characters

string(Address Line 2)<= 50 characters

city_localityCity Locality (string) or City Locality (null)(City Locality)

The city or locality of the address

Example: "San Francisco"

Any of:

The city or locality of the address

<= 64 characters

string(City Locality)<= 64 characters

state_provinceState Province (string) or State Province (null)(State Province)

The state, province, county, or municipal division

Example: "CA"

Any of:

The state, province, county, or municipal division

<= 32 characters

string(State Province)<= 32 characters

postal_codePostal Code (string) or null(Postal Code)

The postal code or zip code

Example: "94103"

Any of:

The postal code or zip code

<= 16 characters

string(Postal Code)<= 16 characters

country_codestring(Country Code)= 2 charactersrequired

The ISO 3166 country code

Example: "US"

address_typestring(AddressType)

The residential/commercial type of the address from the delivery/pickup standpoint

unknown At the moment it is not possible to establish if the address is of any known type

residential The address is a residence

commercial The address is associated with a business

po_box The address is a PO Box

military The address is a military address

Default "unknown"

Enum"unknown""residential""commercial""po_box""military"

Example: "residential"

curl -i -X PUT \
'https://api.goshippo.com/v2/addresses/{address_id}' \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "name": "Wilson",
  "organization": "Shippo",
  "email": "user@shippo.com",
  "phone": "+1-4155550132",
  "address_line_1": "731 Market Street",
  "address_line_2": "#200",
  "city_locality": "San Francisco",
  "state_province": "CA",
  "postal_code": "94103",
  "country_code": "US",
  "address_type": "residential"
}'

Responses

Successful Response

Response

No content

Delete an address

Request

Removes an existing address from your address book using an object ID

Security

Shippo_Token

Path

address_idstring(Address Id)required

curl -i -X DELETE \
'https://api.goshippo.com/v2/addresses/{address_id}' \
-H 'Authorization: ShippoToken <API_TOKEN>'

Responses

Successful Response

Response

No content

Create a new address

Request

Stores a new address to your address book

Security

Shippo_Token

Bodyapplication/jsonrequired

namestring(Name)<= 64 charactersrequired

The name of the addressee

Example: "Wilson"

organizationOrganization (string) or Organization (null)(Organization)

The organization of the addressee

Example: "Shippo"

Any of:

The organization of the addressee

<= 100 characters

string(Organization)<= 100 characters

emailEmail (string) or Email (null)(Email)

The email of the addressee

Example: "user@shippo.com"

Any of:

The email of the addressee

[ 5 .. 128 ] characters

string(email)(Email)[ 5 .. 128 ] characters

phonePhone (string) or Phone (null)(Phone)

The phone number of the addressee

Example: "+1-4155550132"

Any of:

The phone number of the addressee

[ 3 .. 32 ] characters

string(Phone)[ 3 .. 32 ] characters

address_line_1string(Address Line 1)[ 1 .. 100 ] charactersrequired

The first line of the address

Example: "731 Market Street"

address_line_2Address Line 2 (string) or Address Line 2 (null)(Address Line 2)

The second line of the address

Example: "#200"

Any of:

The second line of the address

<= 50 characters

string(Address Line 2)<= 50 characters

city_localityCity Locality (string) or City Locality (null)(City Locality)

The city or locality of the address

Example: "San Francisco"

Any of:

The city or locality of the address

<= 64 characters

string(City Locality)<= 64 characters

state_provinceState Province (string) or State Province (null)(State Province)

The state, province, county, or municipal division

Example: "CA"

Any of:

The state, province, county, or municipal division

<= 32 characters

string(State Province)<= 32 characters

postal_codePostal Code (string) or null(Postal Code)

The postal code or zip code

Example: "94103"

Any of:

The postal code or zip code

<= 16 characters

string(Postal Code)<= 16 characters

country_codestring(Country Code)= 2 charactersrequired

The ISO 3166 country code

Example: "US"

address_typestring(AddressType)

The residential/commercial type of the address from the delivery/pickup standpoint

unknown At the moment it is not possible to establish if the address is of any known type

residential The address is a residence

commercial The address is associated with a business

po_box The address is a PO Box

military The address is a military address

Default "unknown"

Enum"unknown""residential""commercial""po_box""military"

Example: "residential"

curl -i -X POST \
https://api.goshippo.com/v2/addresses \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "name": "Wilson",
  "organization": "Shippo",
  "email": "user@shippo.com",
  "phone": "+1-4155550132",
  "address_line_1": "731 Market Street",
  "address_line_2": "#200",
  "city_locality": "San Francisco",
  "state_province": "CA",
  "postal_code": "94103",
  "country_code": "US",
  "address_type": "residential"
}'

Responses

Successful Response

Bodyapplication/json

Any of:

idstring(Id)required

Example: "e9f1f6fd20f84982afe471ff06c5a80f"

addressobject(Address)required

updated_atstring(date-time)(Updated At)required

created_atstring(date-time)(Created At)required

Response

application/json

{
  "id": "e9f1f6fd20f84982afe471ff06c5a80f",
  "address": {
    "name": "Wilson",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "organization": "Shippo",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve addresses

Request

Returns a list of addresses based on search criteria

Security

Shippo_Token

Query

offsetinteger(Offset)>= 0

Default 0

limitinteger(Limit)>= 1

Default 30

searchstring(Search)

curl -i -X GET \
'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string' \
-H 'Authorization: ShippoToken <API_TOKEN>'

Responses

Successful Response

Bodyapplication/json

offsetOffset (integer) or Offset (null)(Offset)

Example: 1

Any of:

integer(Offset)

limitLimit (integer) or Limit (null)(Limit)

Example: 1

Any of:

integer(Limit)

countinteger(Count)required

Example: 1

nextNext (string) or Next (null)(Next)

Example: "/addresses?offset=2&limit=1"

Any of:

string(Next)

prevPrev (string) or Prev (null)(Prev)

Example: "/addresses?offset=0&limit=1"

Any of:

string(Prev)

resultsArray of objects(Results)required

Response

application/json

{
  "offset": 1,
  "limit": 1,
  "count": 1,
  "next": "/addresses?offset=2&limit=1",
  "prev": "/addresses?offset=0&limit=1",
  "results": [
    { … }
  ]
}

Validation

Check your address is valid before creating shipping labels

Operations

Parser

Convert address strings into a correctly formatted address object

Operations

Shippo Address API (0.1)

Address Book