Address Validation

In the world of payroll, address validity is very important. For example, some states have payroll taxes that apply to residents based on the school district they live in. This type of regulatory requirement makes it important for Check’s systems to be able to locate an employee’s residence or workplace address in order to properly calculate taxes.

To enable this, Check relies on a third-party address validation service that looks up addresses in the same database used by the United States Postal Service. In the event that a match is not found, Check’s API will return an error to the user. In many cases (though not all), a suggested alternative will also be provided in the API response. Note: the suggested alternative returned by our API is not guaranteed to be valid.

Below is an example of a request to validate an address with an invalid zip code. This request leverages Check's Address Validation endpoint, but these validations will also run when addresses are passed into Check's Workplace, Employee, Company, and Contractor APIs.

You can see below that the API returns a suggested alternative that contains the corrected zip code.

Request:

curl -XPOST https://sandbox.checkhq.com/addresses/validate -d '{
	"line1": "728 Castro St",
	"city": "San Francisco",
	"state": "CA",
	"postal_code": "11111"
}'

Reponse:

{
    "error": {
        "type": "address_invalid",
        "message": "Invalid address: Incorrect postal code",
        "suggested_alternative": {
            "line1": "728 Castro St",
            "line2": null,
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94114"
        }
    }
}

There are a number of possible messages that can accompany an address_invalid API response:

• Invalid address: Incorrect postal code
• Invalid address: Incorrect state
• Invalid address: Incorrect city
• Invalid address: Foreign address
• Invalid address: Unknown street
• Invalid address: Multiple matches returned
• Invalid address: The premise (house or building) number for the address is not valid
• Invalid address: Invalid premise number
• Invalid address: Invalid postal code

If you are encounter a validation error on an address that you believe to be legitimate, please reach out to mailto:[email protected] for assistance.