Looking for the old docs? View our old docs site.
API Docs

Address

Address objects are used to represent people, places, and organizations in a number of contexts. For example, a Shipment requires a to_address and from_address to accurately calculate rates and generate postage.

Additionally, EasyPost offers several verification tools that can be used to detect deliverability issues, correct minor errors in spelling/formatting, and determine if an address is residential or not (which has a significant effect on Shipment rating for many carriers).

Endpoints
POST
/addresses
GET
/addresses
GET
/addresses/:id

Address object

id
string
Unique identifier, begins with "adr_"
object
string
"Address"
mode
string
Set based on which api-key you used, either "test" or "production"
street1
string
First line of the address
street2
string
Second line of the address
city
string
City the address is located in
state
string
State or province the address is located in
zip
string
ZIP or postal code the address is located in
country
string
ISO 3166 country code for the country the address is located in
residential
boolean
Whether or not this address would be considered residential
carrier_facility
string
The specific designation for the address (only relevant if the address is a carrier facility).
name
string
Name of the person. Both name and company can be included.
company
string
Name of the organization. Both name and company can be included.
phone
string
Phone number to reach the person or organization
email
string
Email to reach the person or organization
federal_tax_id
string
Federal tax identifier of the person or organization
state_tax_id
string
State tax identifier of the person or organization
verifications
The result of any verifications requested
Address Object
{
  "id": "adr_3a2086e3bafa11eeb8d4ac1f6bc539ae",
  "object": "Address",
  "created_at": "2024-01-24T20:50:37+00:00",
  "updated_at": "2024-01-24T20:50:37+00:00",
  "name": null,
  "company": "EasyPost",
  "street1": "417 MONTGOMERY ST",
  "street2": "FLOOR 5",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": null,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {}
}

Verifications object

zip4
Only applicable to US addresses - checks and sets the ZIP+4
delivery
Checks that the address is deliverable and makes minor corrections to spelling or format. US addresses will also have their residential status checked and set.
Verifications Object
{
  "zip4": {
    "success": true,
    "errors": [],
    "details": null
  },
  "delivery": {
    "success": true,
    "errors": [],
    "details": {
      "latitude": 37.79342,
      "longitude": -122.40288,
      "time_zone": "America/Los_Angeles"
    }
  }
}

Verification object

success
boolean
The success of the verification
errors
All errors that caused the verification to fail
details
Extra data related to the verification
Verification Object
{
  "success": true,
  "errors": [],
  "details": {
    "latitude": 37.79342,
    "longitude": -122.40288,
    "time_zone": "America/Los_Angeles"
  }
}

VerificationDetails object

latitude
number
The latitude
longitude
number
The longitude
time_zone
TZ (string)
The time zone the address is located in, e.g. America/Los_Angeles
VerificationDetails Object
{
  "latitude": 37.79342,
  "longitude": -122.40288,
  "time_zone": "America/Los_Angeles"
}

Address Verification by Country

Our address verification service supports 240+ countries. See our full listing to see which verification level is available for each country. We are constantly working to expand our coverage of addresses worldwide.

FULL LIST OF COUNTRIES AND LEVELS

Create and Verify Addresses

Depending on your use case an Address can be used in many different ways. Certain carriers allow rating between two zip codes, but full addresses are required to purchase postage. It is recommended to provide as much information as possible during creation and to reuse these objects whenever possible.

Address objects can also be created inline while creating another object, for example during Shipment creation.

An Address object is immutable once created. All information must be provided during creation; it cannot be modified later.

Verify an Address

Verifying an Address before you ship is a great way to reduce issues with delivery.

Creating a verified Address is as simple as providing verify or verify_strict in the parameters. If any of the strict verification checks fail, an error will be returned from the API. The example below demonstrates verifying delivery, which checks that the address is deliverable and sets its residential delivery indicator.

The most effective time to perform address verification is when your customer, or the person entering the delivery address, is present. When designing a shopping cart it is recommended to ask the shopper for their address and verify it on the spot. If verification fails, ask them to double check their input; if they confirm that their data is correct, assume they know their address more correctly than the verification process.

Request Parameters

street1
i.e. 417 Montgomery St
First line of the address
street2
i.e. Floor 5
Second line of the address
city
i.e. San Francisco
Full city name
state
i.e. CA
State or province
zip
i.e. 94104
ZIP or postal code
country
i.e. US
ISO 3166 country code for the country the address is located in
name
i.e. Hiro Protagonist
Name of attention, if person. Both name and company can be included.
company
i.e. EasyPost
Name of attention, if organization. Both name and company can be included.
phone
i.e. 415-123-4567
Phone number to reach the person or organization
email
i.e. example@example.com
Email to reach the person or organization
residential
i.e. false
Residential delivery indicator
carrier_facility
i.e. ONDC
The specific designation for the address (only relevant if the address is a carrier facility)
federal_tax_id
i.e. 1234567890
Federal tax identifier of the person or organization
state_tax_id
i.e. 9876543210
State tax identifier of the person or organization
verify
i.e. true
Include to perform verifications on delivery and zip code. verify_strict takes precedence if also included.
verify_strict
i.e. true
Include to perform strict verifications on delivery and zip code. The failure of any of these verifications causes the whole request to fail.
POST /addresses
1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "street1": "417 MONTGOMERY ST",
7      "street2": "FLOOR 5",
8      "city": "SAN FRANCISCO",
9      "state": "CA",
10      "zip": "94104",
11      "country": "US",
12      "company": "EasyPost",
13      "phone": "415-123-4567"
14    }
15  }'
Response
1{
2  "id": "adr_3a2086e3bafa11eeb8d4ac1f6bc539ae",
3  "object": "Address",
4  "created_at": "2024-01-24T20:50:37+00:00",
5  "updated_at": "2024-01-24T20:50:37+00:00",
6  "name": null,
7  "company": "EasyPost",
8  "street1": "417 MONTGOMERY ST",
9  "street2": "FLOOR 5",
10  "city": "SAN FRANCISCO",
11  "state": "CA",
12  "zip": "94104",
13  "country": "US",
14  "phone": "4151234567",
15  "email": null,
16  "mode": "test",
17  "carrier_facility": null,
18  "residential": null,
19  "federal_tax_id": null,
20  "state_tax_id": null,
21  "verifications": {}
22}
Create and Verify
1curl -X POST https://api.easypost.com/v2/addresses/create_and_verify \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "street1": "000 unknown street",
7      "city": "Not A City",
8      "state": "ZZ",
9      "zip": "00001",
10      "country": "US",
11      "email": "test@example.com",
12      "phone": "5555555555"
13    }
14  }'
Response
1{
2  "error": {
3    "code": "ADDRESS.VERIFY.FAILURE",
4    "message": "Unable to verify address.",
5    "errors": [
6      {
7        "code": "E.ADDRESS.NOT_FOUND",
8        "field": "address",
9        "message": "Address not found",
10        "suggestion": null
11      }
12    ]
13  }
14}
Verifying an Address
1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "street1": "000 unknown street",
7      "city": "Not A City",
8      "state": "ZZ",
9      "zip": "00001",
10      "country": "US",
11      "email": "test@example.com",
12      "phone": "5555555555"
13    },
14    "verify": true
15  }'
Response
1{
2  "id": "adr_3a98ffc7bafa11eeb8fcac1f6bc539ae",
3  "object": "Address",
4  "created_at": "2024-01-24T20:50:38+00:00",
5  "updated_at": "2024-01-24T20:50:38+00:00",
6  "name": null,
7  "company": "EasyPost",
8  "street1": "000 unknown street",
9  "street2": null,
10  "city": "Not A City",
11  "state": "ZZ",
12  "zip": "00001",
13  "country": "US",
14  "phone": "5555555555",
15  "email": "test@example.com",
16  "mode": "test",
17  "carrier_facility": null,
18  "residential": null,
19  "federal_tax_id": null,
20  "state_tax_id": null,
21  "verifications": {
22    "zip4": {
23      "success": false,
24      "errors": [
25        {
26          "code": "E.ADDRESS.NOT_FOUND",
27          "field": "address",
28          "message": "Address not found",
29          "suggestion": null
30        }
31      ],
32      "details": null
33    },
34    "delivery": {
35      "success": false,
36      "errors": [
37        {
38          "code": "E.ADDRESS.NOT_FOUND",
39          "field": "address",
40          "message": "Address not found",
41          "suggestion": null
42        }
43      ],
44      "details": {}
45    }
46  }
47}
Verifying an Invalid Address
1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "street1": "000 unknown street",
7      "city": "Not A City",
8      "state": "ZZ",
9      "zip": "00001",
10      "country": "US",
11      "email": "test@example.com",
12      "phone": "5555555555"
13    }
14  }'
Response
1{
2  "error": {
3    "code": "ADDRESS.VERIFY.FAILURE",
4    "message": "Unable to verify address.",
5    "errors": [
6      {
7        "code": "E.ADDRESS.NOT_FOUND",
8        "field": "address",
9        "message": "Address not found",
10        "suggestion": null
11      }
12    ]
13  }
14}
Strict-Verifying an Address
1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "street1": "000 unknown street",
7      "city": "Not A City",
8      "state": "ZZ",
9      "zip": "00001",
10      "country": "US",
11      "email": "test@example.com",
12      "phone": "5555555555"
13    },
14    "verify_strict": true
15  }'
Response
1{
2  "error": {
3    "code": "ADDRESS.VERIFY.FAILURE",
4    "message": "Unable to verify address.",
5    "errors": [
6      {
7        "code": "E.ADDRESS.NOT_FOUND",
8        "field": "address",
9        "message": "Address not found",
10        "suggestion": null
11      }
12    ]
13  }
14}
Verify an Existing Address
1curl -X GET https://api.easypost.com/v2/addresses/adr_.../verify \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "address": {
3    "id": "adr_3b15ed39bafa11ee83ed3cecef1b359e",
4    "object": "Address",
5    "created_at": "2024-01-24T20:50:39+00:00",
6    "updated_at": "2024-01-24T20:50:39+00:00",
7    "name": null,
8    "company": "EASYPOST",
9    "street1": "417 MONTGOMERY ST FL 5",
10    "street2": "",
11    "city": "SAN FRANCISCO",
12    "state": "CA",
13    "zip": "94104-1129",
14    "country": "US",
15    "phone": "4151234567",
16    "email": null,
17    "mode": "test",
18    "carrier_facility": null,
19    "residential": false,
20    "federal_tax_id": null,
21    "state_tax_id": null,
22    "verifications": {
23      "zip4": {
24        "success": true,
25        "errors": [],
26        "details": null
27      },
28      "delivery": {
29        "success": true,
30        "errors": [],
31        "details": {
32          "latitude": 37.79342,
33          "longitude": -122.40288,
34          "time_zone": "America/Los_Angeles"
35        }
36      }
37    }
38  }
39}

Retrieve all Addresses

A list of all Address objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. adr_...
Optional pagination parameter. Only events created before the given ID will be included. May not be used with after_id
after_id
i.e. adr_...
Optional pagination parameter. Only events created after the given ID will be included. May not be used with before_id
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /addresses
1curl -X GET https://api.easypost.com/v2/addresses?page_size=5 \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "addresses": [
3    {
4      "id": "adr_3b7de31bbafa11eeb947ac1f6bc539ae",
5      "object": "Address",
6      "created_at": "2024-01-24T20:50:39+00:00",
7      "updated_at": "2024-01-24T20:50:39+00:00",
8      "name": null,
9      "company": "EasyPost",
10      "street1": "417 MONTGOMERY ST",
11      "street2": "FLOOR 5",
12      "city": "SAN FRANCISCO",
13      "state": "CA",
14      "zip": "94104",
15      "country": "US",
16      "phone": "4151234567",
17      "email": null,
18      "mode": "test",
19      "carrier_facility": null,
20      "residential": null,
21      "federal_tax_id": null,
22      "state_tax_id": null,
23      "verifications": {}
24    }
25  ],
26  "has_more": true
27}

Retrieve an Address

An Address can be retrieved by its id.

GET /addresses/:id
1curl -X GET https://api.easypost.com/v2/addresses/adr_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "adr_3b7de31bbafa11eeb947ac1f6bc539ae",
3  "object": "Address",
4  "created_at": "2024-01-24T20:50:39+00:00",
5  "updated_at": "2024-01-24T20:50:39+00:00",
6  "name": null,
7  "company": "EasyPost",
8  "street1": "417 MONTGOMERY ST",
9  "street2": "FLOOR 5",
10  "city": "SAN FRANCISCO",
11  "state": "CA",
12  "zip": "94104",
13  "country": "US",
14  "phone": "4151234567",
15  "email": null,
16  "mode": "test",
17  "carrier_facility": null,
18  "residential": null,
19  "federal_tax_id": null,
20  "state_tax_id": null,
21  "verifications": {}
22}