UPS - Validate Address

Description

This module validates a shipping address using the UPS Address Validation (XAV) service. It receives the address, city, state, zip code, and country. It makes a POST request to the /api/addressvalidation/v1/1 endpoint with the XAVRequest format. It returns whether the address is valid, the corrected candidate address, the classification (Residential or Commercial), and whether no candidates were found.

Configuration

Parameter	Type	Required	Description
credentials_id	credentials	Yes	UPS credential (provider: ups)
street	text	Yes	Main address line
city	text	Yes	City
state	text	Yes	State or province
postal_code	text	Yes	Zip code
country_code	text	Yes	ISO country code (default: US)

Credentials

A ups type credential is required with the following fields:

client_id: UPS API Client ID
client_secret: UPS API Client Secret

Output

{
  "success": true,
  "valid": true,
  "candidate": {
    "AddressLine": ["123 MAIN ST"],
    "PoliticalDivision2": "MEMPHIS",
    "PoliticalDivision1": "TN",
    "PostcodePrimaryLow": "38118",
    "CountryCode": "US"
  },
  "classification": "Residential",
  "is_residential": true,
  "no_candidates": false,
  "message": "Direccion validada: Residential"
}

Usage Example

Basic case

{
  "credentials_id": "mi_credencial_ups",
  "street": "123 Main Street",
  "city": "Memphis",
  "state": "TN",
  "postal_code": "38118",
  "country_code": "US"
}

API Used

Endpoint: POST /api/addressvalidation/v1/1
Base: UPS API (via helper _upsHelper)
Documentation: https://developer.ups.com/api/reference

Notes

The request format uses XAVRequest with AddressKeyFormat
UPS internal field names use PoliticalDivision1 (state) and PoliticalDivision2 (city)
The no_candidates field indicates whether UPS could not find any candidate address
The classification can be “Residential” or “Commercial”
The first candidate from the response is used