### API Overview: Address Validation - Street Level Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml 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 - Appendix - Business Rules - Errors - FAQ - Accelerate API Integration with UPS MCP Server

Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our Postman Guide. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub ```yaml # Address Validation - Street Level # Version: 1.0.0 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 - Appendix - Business Rules - Errors - FAQ - Accelerate API Integration with UPS MCP Server

Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our Postman Guide. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub # Base URL: https://wwwcie.ups.com/api ``` -------------------------------- ### Security: OAuth2 Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Find your Client ID and Secret on your app info page. 1. Select \"Try It\" 2. In the Security section enter your Client ID and Secret. 3. Select \"Request Token\" 4. Enter any additional information in the Body and Parameters sections. 5. Select \"Send\" to execute your API request ```markdown ## Security: OAuth2 **Description:** Find your Client ID and Secret on your app info page. 1. Select \"Try It\" 2. In the Security section enter your Client ID and Secret. 3. Select \"Request Token\" 4. Enter any additional information in the Body and Parameters sections. 5. Select \"Send\" to execute your API request **Type:** oauth2 **OAuth Flows:** - **clientCredentials**: https://wwwcie.ups.com/security/v1/oauth/token - Scopes: ``` -------------------------------- ### Schema: XAVResponseWrapper Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml N/A ```markdown ## Schema: XAVResponseWrapper N/A **Type:** object - **XAVResponse** (object) (required): XAV Response Container. - **Response** (object) (required): Response Container. - **ResponseStatus** (object) (required): Response Status Container. - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. - **Alert** (array (Response_Alert)): Alert Container. There can be zero to many alert containers with code and description. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **TransactionReference** (object): Transaction Reference Container. - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. - **ValidAddressIndicator** (string): Indicates query found a valid match. - **AmbiguousAddressIndicator** (string): Indicates query could not find exact match. Candidate list follows. - **NoCandidatesIndicator** (string): No Candidate found. - **AddressClassification** (object): AddressClassification Container. - **Candidate** (array (XAVResponse_Candidate)): Candidate Container. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **AddressClassification** (object): AddressClassification Container. - **AddressKeyFormat** (object) (required): AddressKeyFormat Container. - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. ``` -------------------------------- ### Schema: XAVRequestWrapper Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml N/A ```markdown ## Schema: XAVRequestWrapper N/A **Type:** object - **XAVRequest** (object) (required) - **AddressKeyFormat** (object) (required): 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): Name of business, company or person. Ignored if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of the building. Ignored if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): 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): 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): City or Town name. - **PoliticalDivision1** (string): State or Province/Territory name. - **PostcodePrimaryLow** (string): Postal Code. - **PostcodeExtendedLow** (string): 4 digit Postal Code extension. For US use only. - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): Country or Territory Code. For a list of valid values, refer to the Address Validation API Supported Countries or Territories table in the Appendix. ``` -------------------------------- ### Schema: Candidate_AddressKeyFormat Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml AddressKeyFormat Container. ```markdown ## Schema: Candidate_AddressKeyFormat AddressKeyFormat Container. **Type:** object - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. ``` -------------------------------- ### Schema: XAVResponse_Candidate Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Schema definition for XAVResponse_Candidate ```markdown ## Schema: XAVResponse_Candidate Schema definition for XAVResponse_Candidate **Type:** object - **AddressClassification** (object): AddressClassification Container. - **Code** (string) (required): Contains the classification code of the address: 0 - UnClassified 1 - Commercial 2 - Residential - **Description** (string) (required): Contains the text description of the address classification code (see Code above). - **AddressKeyFormat** (object) (required): AddressKeyFormat Container. - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. ``` -------------------------------- ### Schema: Candidate_AddressClassification Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml AddressClassification Container. ```markdown ## Schema: Candidate_AddressClassification AddressClassification Container. **Type:** object - **Code** (string) (required): Contains the classification code of the address: 0 - UnClassified 1 - Commercial 2 - Residential - **Description** (string) (required): Contains the text description of the address classification code (see Code above). ``` -------------------------------- ### Schema: XAVResponse Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml XAV Response Container. ```markdown ## Schema: XAVResponse XAV Response Container. **Type:** object - **Response** (object) (required): Response Container. - **ResponseStatus** (object) (required): Response Status Container. - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. - **Alert** (array (Response_Alert)): Alert Container. There can be zero to many alert containers with code and description. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **TransactionReference** (object): Transaction Reference Container. - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. - **ValidAddressIndicator** (string): Indicates query found a valid match. - **AmbiguousAddressIndicator** (string): Indicates query could not find exact match. Candidate list follows. - **NoCandidatesIndicator** (string): No Candidate found. - **AddressClassification** (object): AddressClassification Container. - **Candidate** (array (XAVResponse_Candidate)): Candidate Container. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **AddressClassification** (object): AddressClassification Container. - **AddressKeyFormat** (object) (required): AddressKeyFormat Container. - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. ``` -------------------------------- ### Schema: XAVResponse_AddressClassification Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml AddressClassification Container. ```markdown ## Schema: XAVResponse_AddressClassification AddressClassification Container. **Type:** object - **Code** (string) (required): Contains the classification code of the input address. Valid values: - 0 - UnClassified - 1 - Commercial - 2 - Residential - **Description** (string) (required): Contains the text description of the address classification code: UnClassified, Commercial, Residential ``` -------------------------------- ### Schema: XAVResponse_Response Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Response Container. ```markdown ## Schema: XAVResponse_Response Response Container. **Type:** object - **ResponseStatus** (object) (required): Response Status Container. - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. - **Alert** (array (Response_Alert)): Alert Container. There can be zero to many alert containers with code and description. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **TransactionReference** (object): Transaction Reference Container. - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. ``` -------------------------------- ### Schema: XAVRequest_AddressKeyFormat Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml 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. ```markdown ## Schema: XAVRequest_AddressKeyFormat 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. **Type:** object - **ConsigneeName** (string): Name of business, company or person. Ignored if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of the building. Ignored if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): 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): 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): City or Town name. - **PoliticalDivision1** (string): State or Province/Territory name. - **PostcodePrimaryLow** (string): Postal Code. - **PostcodeExtendedLow** (string): 4 digit Postal Code extension. For US use only. - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): Country or Territory Code. For a list of valid values, refer to the Address Validation API Supported Countries or Territories table in the Appendix. ``` -------------------------------- ### Schema: Response_Alert Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Schema definition for Response_Alert ```markdown ## Schema: Response_Alert Schema definition for Response_Alert **Type:** object - **Code** (string) (required): Warning code returned by the system. - **Description** (string) (required): Warning messages returned by the system. ``` -------------------------------- ### Schema: Response_ResponseStatus Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Response Status Container. ```markdown ## Schema: Response_ResponseStatus Response Status Container. **Type:** object - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. ``` -------------------------------- ### Schema: XAVRequest Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Schema definition for XAVRequest ```markdown ## Schema: XAVRequest Schema definition for XAVRequest **Type:** object - **AddressKeyFormat** (object) (required): 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): Name of business, company or person. Ignored if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of the building. Ignored if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): 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): 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): City or Town name. - **PoliticalDivision1** (string): State or Province/Territory name. - **PostcodePrimaryLow** (string): Postal Code. - **PostcodeExtendedLow** (string): 4 digit Postal Code extension. For US use only. - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): Country or Territory Code. For a list of valid values, refer to the Address Validation API Supported Countries or Territories table in the Appendix. ``` -------------------------------- ### Schema: Response_TransactionReference Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Transaction Reference Container. ```markdown ## Schema: Response_TransactionReference Transaction Reference Container. **Type:** object - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. ``` -------------------------------- ### Schema: CommonErrorResponse Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml The error response containing any errors that occurred. ```markdown ## Schema: CommonErrorResponse The error response containing any errors that occurred. **Type:** object - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. ``` -------------------------------- ### Schema: ErrorResponse Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml Schema definition for ErrorResponse ```markdown ## Schema: ErrorResponse Schema definition for ErrorResponse **Type:** object - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. ``` -------------------------------- ### Schema: ErrorMessage Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml The error response containing any errors that occurred. ```markdown ## Schema: ErrorMessage The error response containing any errors that occurred. **Type:** object - **code** (string): The error code. - **message** (string): The error message. ``` -------------------------------- ### POST /addressvalidation/{version}/{requestoption} Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml 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). ```markdown ### Parameters - **regionalrequestindicator** (string, query, optional): 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, query, optional): Valid values: 0 – 50 The maximum number of Candidates to return for this request. If not provided, the default size of 15 is returned. - **requestoption** (integer, path, required): 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** (string, path, required): Identifies the version of the API. Valid values: - v2 ### Request Body **Content-Type:** application/json - **XAVRequest** (object) (required) - **AddressKeyFormat** (object) (required): 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): Name of business, company or person. Ignored if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of the building. Ignored if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): 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): 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): City or Town name. - **PoliticalDivision1** (string): State or Province/Territory name. - **PostcodePrimaryLow** (string): Postal Code. - **PostcodeExtendedLow** (string): 4 digit Postal Code extension. For US use only. - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): 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 **XAVResponseWrapper** - **XAVResponse** (object) (required): XAV Response Container. - **Response** (object) (required): Response Container. - **ResponseStatus** (object) (required): Response Status Container. - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. - **Alert** (array (Response_Alert)): Alert Container. There can be zero to many alert containers with code and description. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **TransactionReference** (object): Transaction Reference Container. - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. - **ValidAddressIndicator** (string): Indicates query found a valid match. - **AmbiguousAddressIndicator** (string): Indicates query could not find exact match. Candidate list follows. - **NoCandidatesIndicator** (string): No Candidate found. - **AddressClassification** (object): AddressClassification Container. - **Candidate** (array (XAVResponse_Candidate)): Candidate Container. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **AddressClassification** (object): AddressClassification Container. - **AddressKeyFormat** (object) (required): AddressKeyFormat Container. - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. #### 400 - Invalid Request **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 401 - Unauthorized Request **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 403 - Blocked Merchant **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 429 - Rate Limit Exceeded **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. ### Example Usage ```bash curl -X POST "https://wwwcie.ups.com/api/addressvalidation/{version}/{requestoption}?regionalrequestindicator=string&maximumcandidatelistsize=0" \ -H "Content-Type: application/json" \ -d '{ "XAVRequest": "value" }' ``` ``` -------------------------------- ### POST /addressvalidation/{deprecatedVersion}/{requestoption} Source: https://raw.githubusercontent.com/UPS-API/api-documentation/refs/heads/main/AddressValidation.yaml 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. ```markdown ### Parameters - **regionalrequestindicator** (string, query, optional): 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, query, optional): Valid values: 0 – 50 The maximum number of Candidates to return for this request. If not provided, the default size of 15 is returned. - **requestoption** (integer, path, required): 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** (string, path, required): Identifies the version of the API. Valid values: - v1 ### Request Body **Content-Type:** application/json - **XAVRequest** (object) (required) - **AddressKeyFormat** (object) (required): 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): Name of business, company or person. Ignored if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of the building. Ignored if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): 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): 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): City or Town name. - **PoliticalDivision1** (string): State or Province/Territory name. - **PostcodePrimaryLow** (string): Postal Code. - **PostcodeExtendedLow** (string): 4 digit Postal Code extension. For US use only. - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): 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 **XAVResponseWrapper** - **XAVResponse** (object) (required): XAV Response Container. - **Response** (object) (required): Response Container. - **ResponseStatus** (object) (required): Response Status Container. - **Code** (string) (required): Identifies the success or failure of the transaction. Valid values: 1 = Success 0 = Failure - **Description** (string) (required): Describes Response Status Code. Returns text of 'Success' or 'Failure'. - **Alert** (array (Response_Alert)): Alert Container. There can be zero to many alert containers with code and description. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **TransactionReference** (object): Transaction Reference Container. - **CustomerContext** (string): The CustomerContext Information which will be echoed during response. - **ValidAddressIndicator** (string): Indicates query found a valid match. - **AmbiguousAddressIndicator** (string): Indicates query could not find exact match. Candidate list follows. - **NoCandidatesIndicator** (string): No Candidate found. - **AddressClassification** (object): AddressClassification Container. - **Candidate** (array (XAVResponse_Candidate)): Candidate Container. **NOTE:** For versions >= v2, this element will always be returned as an array. For requests using version = v1, this element will be returned as an array if there is more than one object and a single object if there is only 1. Array items: - **AddressClassification** (object): AddressClassification Container. - **AddressKeyFormat** (object) (required): AddressKeyFormat Container. - **ConsigneeName** (string): Name of business, company or person. Not returned if user selects the RegionalRequestIndicator. - **AttentionName** (string): Name of building. Not returned if user selects the RegionalRequestIndicator. - **AddressLine** (array (string)): Address line (street number, street name and street type, and political division 1, political division 2 and postal code) used for street level information. Additional secondary information (apartment, suite, floor, etc.) Applicable to US and PR only. Not returned if user selects the RegionalRequestIndicator. - **Region** (string): Single entry containing in this order Political Division 2, Political Division 1 and Post Code Primary Low and/or PostcodeExtendedLow. - **PoliticalDivision2** (string): City or Town name. - **PoliticalDivision1** (string): State/Province. Returned if the location is within a State/Province/Territory. For International: returned if user enters valid Country or Territory Code, and City/postal code and it has a match. For Domestic addresses, the value must be a valid 2-character value (per US Mail standards). For International the full State or Province name will be returned. - **PostcodePrimaryLow** (string): Low-end Postal Code. Returned for countries or territories with Postal Codes. May be alphanumeric. - **PostcodeExtendedLow** (string): Low-end extended postal code in a range. Example in quotes: Postal Code 30076-'1234'. Only returned in candidate list. May be alphanumeric - **Urbanization** (string): Puerto Rico Political Division 3. Only Valid for Puerto Rico. - **CountryCode** (string) (required): A country or territory code. Required to be returned. #### 400 - Invalid Request **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 401 - Unauthorized Request **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 403 - Blocked Merchant **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. #### 429 - Rate Limit Exceeded **ErrorResponse** - **response** (object): The error response containing any errors that occurred. - **errors** (array (ErrorMessage)): The error array containing any errors that occurred. Array items: - **code** (string): The error code. - **message** (string): The error message. ### Example Usage ```bash curl -X POST "https://wwwcie.ups.com/api/addressvalidation/{deprecatedVersion}/{requestoption}?regionalrequestindicator=string&maximumcandidatelistsize=0" \ -H "Content-Type: application/json" \ -d '{ "XAVRequest": "value" }' ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.