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
POST
/addresses/create_and_verify
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_7c2f357c2d1511f087fbac1f6bc539ae",
  "object": "Address",
  "created_at": "2025-05-09T20:37:54+00:00",
  "updated_at": "2025-05-09T20:37:54+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

The address verification service supports over 240 countries and territories. Verification levels vary by country. Coverage is continuously expanding to support more global addresses.

Create an Address

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.

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.
verify_carrier
i.e. ups
If set to "ups" or "fedex" and used in combination with verify or verify_strict (true), the address will be verified against the specified carrier's Address Verification Service (AVS). If omitted or null, the request defaults to standard EasyPost verification.
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_7c2f357c2d1511f087fbac1f6bc539ae",
3  "object": "Address",
4  "created_at": "2025-05-09T20:37:54+00:00",
5  "updated_at": "2025-05-09T20:37:54+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}

Verify an Address

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

An address can be verified by including one of the following parameters during creation:

  • verify: Performs standard delivery and ZIP+4 checks.
  • verify_strict: Performs strict verification. If any check fails, the request will return an error.
  • verify_carrier: Allows carrier-grade verification with UPS or FedEx. Must be set to "ups" or "fedex" and used in combination with verify or verify_strict (true).

The most effective time to perform address verification is when the delivery address is entered. If verification fails, request confirmation from the person entering the data, as they may know their address more accurately than the verification process.

The examples below demonstrate different verification options, including delivery checks and strict verification.

Note: As of August 25, 2025, EasyPost only abbreviates street names for USPS address verification when the validated street1 field exceeds 40 characters.

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_7c64776f2d1511f082fc3cecef1b359e",
3  "object": "Address",
4  "created_at": "2025-05-09T20:37:55+00:00",
5  "updated_at": "2025-05-09T20:37:55+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}
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_7cac5ead2d1511f08839ac1f6bc539ae",
4    "object": "Address",
5    "created_at": "2025-05-09T20:37:55+00:00",
6    "updated_at": "2025-05-09T20:37:55+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_827a131c2d1511f086743cecef1b359e",
5      "object": "Address",
6      "created_at": "2025-05-09T20:38:05+00:00",
7      "updated_at": "2025-05-09T20:38:05+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_827a131c2d1511f086743cecef1b359e",
3  "object": "Address",
4  "created_at": "2025-05-09T20:38:05+00:00",
5  "updated_at": "2025-05-09T20:38:05+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}