API Reference | ReDoc

Address Validation

The Address Validation Street Level API can be used to. check addresses against the United States Postal Service database of valid addresses in the U.S. and Puerto Rico.

Reference


Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub

Address Validation

The Address Validation Street Level API can be used to check addresses against the United States Postal Service database of valid addresses in the U.S. and Puerto Rico.

NOTE: In the Customer Integration Environment, Street Level Address Validation will only produce results for addresses in New York (NY) and California (CA).

SecurityOAuth2
Request
path Parameters
requestoption
required
integer >= 1

Identifies the optional processing to be performed. If not present or invalid value then an error will be sent back.

Valid values:

  • 1 - Address Validation
  • 2 - Address Classification
  • 3 - Address Validation and Address Classification.

For a list of valid values, refer to Address Validation API Supported Countries or Territories in the Appendix.

version
required
string >= 1
Default: "v2"

Identifies the version of the API.

Valid values:

  • v2
query Parameters
regionalrequestindicator
string >= 1

Valid values: True or False. If True, either the region element or any combination of Political Division 1, Political Division 2, PostcodePrimaryLow and the PostcodeExtendedLow fields will be recognized for validation in addition to the urbanization element. If False or no indicator, street level address validation is provided

maximumcandidatelistsize
integer >= 1

Valid values: 0 – 50 The maximum number of Candidates to return for this request. If not provided, the default size of 15 is returned.

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1
required
object (XAVRequest)
required
object (XAVRequest_AddressKeyFormat) <= 1

AddressKeyFormat container. The Key format is based on addressing standards jointly developed by the Postal Service and mailing industry. The information provided in the Address Key container will be returned in the same format.

ConsigneeName
string [ 1 .. 40 ] characters <= 1

Name of business, company or person. Ignored if user selects the RegionalRequestIndicator.

AttentionName
string [ 1 .. 40 ] characters <= 1

Name of the building. Ignored if user selects the RegionalRequestIndicator.

AddressLine
Array of strings [ 1 .. 100 ] characters <= 3

Address line (street number, street name and street type) used for street level information. Additional secondary information (apartment, suite, floor, etc.). Applicable to US and PR only. Ignored if user selects the RegionalRequestIndicator.

Region
string [ 1 .. 100 ] characters <= 1

If this node is present the following tags will be ignored:

  • Political Division 2
  • Political Division 1
  • PostcodePrimaryLow
  • PostcodeExtendedLow

Valid only for US or PR origins only. Using this tag for non US/PR origins may cause address format errors.

PoliticalDivision2
string [ 1 .. 30 ] characters <= 1

City or Town name.

PoliticalDivision1
string [ 1 .. 30 ] characters <= 1

State or Province/Territory name.

PostcodePrimaryLow
string [ 1 .. 10 ] characters <= 1

Postal Code.

PostcodeExtendedLow
string [ 1 .. 10 ] characters <= 1

4 digit Postal Code extension. For US use only.

Urbanization
string [ 1 .. 30 ] characters <= 1

Puerto Rico Political Division 3. Only Valid for Puerto Rico.

CountryCode
required
string = 2 characters <= 1

Country or Territory Code. For a list of valid values, refer to the Address Validation API Supported Countries or Territories table in the Appendix.

Responses
200

Successful Operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/addressvalidation/{version}/{requestoption}
Request samples
application/json
{
  • "XAVRequest": {
    }
}
Response samples
application/json
{
  • "XAVResponse": {
    }
}

Address ValidationDeprecated

The Address Validation Street Level API can be used to check addresses against the United States Postal Service database of valid addresses in the U.S. and Puerto Rico.

SecurityOAuth2
Request
path Parameters
requestoption
required
integer >= 1

Identifies the optional processing to be performed. If not present or invalid value then an error will be sent back.

Valid values:

  • 1 - Address Validation
  • 2 - Address Classification
  • 3 - Address Validation and Address Classification.

For a list of valid values, refer to Address Validation API Supported Countries or Territories in the Appendix.

deprecatedVersion
required
string >= 1
Default: "v1"

Identifies the version of the API.

Valid values:

  • v1
query Parameters
regionalrequestindicator
string >= 1

Valid values: True or False. If True, either the region element or any combination of Political Division 1, Political Division 2, PostcodePrimaryLow and the PostcodeExtendedLow fields will be recognized for validation in addition to the urbanization element. If False or no indicator, street level address validation is provided

maximumcandidatelistsize
integer >= 1

Valid values: 0 – 50 The maximum number of Candidates to return for this request. If not provided, the default size of 15 is returned.

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1
required
object (XAVRequest)
required
object (XAVRequest_AddressKeyFormat) <= 1

AddressKeyFormat container. The Key format is based on addressing standards jointly developed by the Postal Service and mailing industry. The information provided in the Address Key container will be returned in the same format.

ConsigneeName
string [ 1 .. 40 ] characters <= 1

Name of business, company or person. Ignored if user selects the RegionalRequestIndicator.

AttentionName
string [ 1 .. 40 ] characters <= 1

Name of the building. Ignored if user selects the RegionalRequestIndicator.

AddressLine
Array of strings [ 1 .. 100 ] characters <= 3

Address line (street number, street name and street type) used for street level information. Additional secondary information (apartment, suite, floor, etc.). Applicable to US and PR only. Ignored if user selects the RegionalRequestIndicator.

Region
string [ 1 .. 100 ] characters <= 1

If this node is present the following tags will be ignored:

  • Political Division 2
  • Political Division 1
  • PostcodePrimaryLow
  • PostcodeExtendedLow

Valid only for US or PR origins only. Using this tag for non US/PR origins may cause address format errors.

PoliticalDivision2
string [ 1 .. 30 ] characters <= 1

City or Town name.

PoliticalDivision1
string [ 1 .. 30 ] characters <= 1

State or Province/Territory name.

PostcodePrimaryLow
string [ 1 .. 10 ] characters <= 1

Postal Code.

PostcodeExtendedLow
string [ 1 .. 10 ] characters <= 1

4 digit Postal Code extension. For US use only.

Urbanization
string [ 1 .. 30 ] characters <= 1

Puerto Rico Political Division 3. Only Valid for Puerto Rico.

CountryCode
required
string = 2 characters <= 1

Country or Territory Code. For a list of valid values, refer to the Address Validation API Supported Countries or Territories table in the Appendix.

Responses
200

Successful Operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/addressvalidation/{deprecatedVersion}/{requestoption}
Request samples
application/json
{
  • "XAVRequest": {
    }
}
Response samples
application/json
{
  • "XAVResponse": {
    }
}
➔ Next to Dangerous Goods