Address Verification Guide

The goal of this guide is to walk you through EasyPost's Address Verification services. We'll give you some background on general AVS, as well as a quick tutorial on how to verify addresses using the EasyPost API. Since this guide requires you to have some knowledge of the EasyPost API, we recommend you check out our Getting Started Guide if you haven't used EasyPost before.

Address verification works through our Address Object and our Verifications Object. Please note that EasyPost will not flag or verify any address unless the verify or verify_strict parameters are used.

When you create an Address Object for your shipment with the aforementioned parameters, you also create associated zip4 or delivery attributes. zip4 only works for U.S. addresses and is used to verify the Zip+4 code of the address. delivery checks the rest of the address to determine its deliverability, and will make minor corrections to spelling/format if applicable.

The results of the verification will show up in the Verifications Object of the Address. The possible responses are:

  • success: the address is verified successfully.
  • errors: the address can't be verified due to an error, which will include error messaging with the response.
  • details: extra data related to the verification, specifically the longitude and latitude of the address.

International AVS works slightly differently. The objects and responses are similar, but zip4 is no longer a valid input to the verify and verify_strict parameters, since international addresses don't have the USPS' Zip+4 postal code. International AVS is also a premium, stand-alone service that must be subscribed to in order to be used. If you'd like to learn more about International AVS, contact our representatives for more information.

Verifying an Address
package example

import (
    "fmt"
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    address, err := client.CreateAndVerifyAddress(
        &easypost.Address{
            Street1: "417 MONTGOMERY ST",
            Street2: "FLOOR 5",
            City:    "SAN FRANCISCO",
            State:   "CA",
            Zip:     "94104",
            Country: "US",
            Company: "EasyPost",
            Phone:   "415-123-4567",
        },
        &easypost.CreateAddressOptions{},
    )

    fmt.Println(address.Street1) // "417 MONTGOMERY ST"
}


    
JSON Response
{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2017-05-08T19:31:54Z",
  "updated_at": "2017-05-08T19:31:54Z",
  "name": null,
  "company": "EASYPOST",
  "street1": "417 MONTGOMERY ST STE 500",
  "street2": "",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104-1100",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": false,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "delivery": {
      "success": true,
      "errors": [],
      "details": {
        "longitude": -122.40288,
        "latitude": 37.79298,
        "time_zone": "America/Los_Angeles"
      }
    }
  }
}
Verifying an invalid Address
package example

import (
    "fmt"
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    address, err := client.CreateAddress(
        &easypost.Address{
            Street1: "UNDELIVERABLE ST", // will fail validation
            Street2: "FLOOR 5",
            City:    "SAN FRANCISCO",
            State:   "CA",
            Zip:     "94104",
            Country: "US",
            Company: "EasyPost",
            Phone:   "415-123-4567",
        },
        &easypost.CreateAddressOptions{
            Verify: []string{"delivery"},
        },
    )

    // address.Verifications has details on validation errors
    fmt.Fprintln(os.Stdout, address.Verifications)
}


    
JSON Response
{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2017-05-08T19:43:41Z",
  "updated_at": "2017-05-08T19:43:41Z",
  "name": null,
  "company": "EasyPost",
  "street1": "UNDELIVERABLE ST",
  "street2": null,
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": false,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "delivery": {
      "success": false,
      "errors": [
        {
          "suggestion": null,
          "code": "E.ADDRESS.NOT_FOUND",
          "field": "address",
          "message": "Address not found"
        },
        {
          "suggestion": null,
          "code": "E.HOUSE_NUMBER.MISSING",
          "field": "street1",
          "message": "House number is missing"
        }
      ],
      "details": {}
    }
  }
}
Strict-Verifying Addresses
package example

import (
    "fmt"
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    address, err := client.CreateAddress(
        &easypost.Address{
            Street1: "UNDELIVERABLE ST", // will fail validation
            Street2: "FLOOR 5",
            City:    "SAN FRANCISCO",
            State:   "CA",
            Zip:     "94104",
            Country: "US",
            Company: "EasyPost",
            Phone:   "415-123-4567",
        },
        &easypost.CreateAddressOptions{
            VerifyStrict: []string{"delivery"},
        },
    )

    // API request throws an error when validation errors occur in strict mode
}


    
JSON Response
{
  "error": {
    "code": "ADDRESS.VERIFY.FAILURE",
    "message": "Unable to verify address.",
    "errors": [
      {
        "suggestion": null,
        "code": "E.ADDRESS.NOT_FOUND",
        "field": "address",
        "message": "Address not found"
      },
      {
        "suggestion": null,
        "code": "E.HOUSE_NUMBER.MISSING",
        "field": "street1",
        "message": "House number is missing"
      }
    ]
  }
}
Verify an already created Address
package example

import (
    "fmt"
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    address, err := client.CreateAddress(
        &easypost.Address{
            Street1: "417 montgomery streat", // will be cleaned up
            Street2: "FLOOR 5",
            City:    "SAN FRANCISCO",
            State:   "CA",
            Zip:     "94104",
            Country: "US",
            Company: "EasyPost",
            Phone:   "415-123-4567",
        },
        &easypost.CreateAddressOptions{
            Verify: []string{"delivery"},
        },
    )

    // address.Verifications will not have any errors listed
    fmt.Fprintln(os.Stdout, address.Verifications)
}


    
JSON Response
{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2017-05-08T19:31:54Z",
  "updated_at": "2017-05-08T19:31:54Z",
  "name": null,
  "company": "EASYPOST",
  "street1": "417 MONTGOMERY ST STE 500",
  "street2": "",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104-1100",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "mode": "test",
  "carrier_facility": null,
  "residential": false,
  "federal_tax_id": null,
  "state_tax_id": null,
  "verifications": {
    "zip4": {
      "success": true,
      "errors": [],
      "details": null
    },
    "delivery": {
      "success": true,
      "errors": [],
      "details": {
        "longitude": -122.40288,
        "latitude": 37.79298,
        "time_zone": "America/Los_Angeles"
      }
    }
  }
}