Skip to navigation
AvaTax quickstart guides

Validate addresses

Normalize and geocode addresses for rooftop-accurate rates.

View as Markdown

US sales tax is jurisdiction-specific, and jurisdictions don’t follow ZIP code boundaries. Resolving an address before you calculate ensures AvaTax assigns the correct state, county, city, and special district rates.

Resolve an address

POST /api/v2/addresses/resolve validates an address, corrects it to a standardized form, and returns latitude/longitude plus the tax authorities that apply.

POST
/api/v2/addresses/resolve
curl -X POST https://rest.avatax.com/api/v2/addresses/resolve \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json-patch+json" \
     -d '{
  "line1": "2000 Main Street",
  "textCase": "Upper",
  "city": "Irvine",
  "region": "CA",
  "country": "US",
  "postalCode": "92614"
}'
Try it
Request
{
  "line1": "88 garden ave",
  "city": "denver",
  "region": "CO",
  "postalCode": "80202",
  "country": "US"
}

Response

The validatedAddresses array contains the corrected address; coordinates returns the geocode; and taxAuthorities lists the jurisdictions that will be applied during calculation.

Response
{
  "address": {
    "line1": "2000 Main Street",
    "city": "Irvine",
    "region": "CA",
    "country": "US",
    "postalCode": "92614"
  },
  "coordinates": {
    "latitude": 33.684884,
    "longitude": -117.851321
  },
  "resolutionQuality": "Intersection",
  "taxAuthorities": [
    {
      "jurisdictionName": "CALIFORNIA",
      "avalaraId": "AGAM",
      "jurisdictionType": "State",
      "signatureCode": "AGAM"
    }
  ],
  "messages": [
    {
      "summary": "The address is not deliverable.",
      "details": "The physical location exists but there are no homes on this street. One reason might be railroad tracks or rivers running alongside this street, as they would prevent construction of homes in this location.",
      "refersTo": "address",
      "severity": "Error",
      "source": "Avalara.AvaTax.Services.Address"
    }
  ]
}

Interpreting messages

The messages array flags anything AvaTax changed or couldn’t confirm.

A refinementLevel at the rooftop or ZIP+4 level means the address resolved cleanly. Store the validated form for future orders.

A message with severity Error means the address couldn’t be matched. Prompt the customer to re-enter it rather than calculating against an unverified location.

Validate at address entry — in the checkout form — not at calculation time. Correcting the address once avoids repeated round-trips and keeps every downstream transaction accurate.