Handle updated addresses

In some cases, you might make multiple calls to the Address Validation API for a single address. For example, the customer might make changes to their address after seeing the results of the first validation. You then perform a second validation on the updated address.

This document describes two key actions you can take when you issue a series of requests for the same address to the Address Validation API. These actions are not a strict usage requirement, but a helpful action on your part to improve overall data quality and system response.

• Send a request to the provideValidationFeedback endpoint
• Set the previousResponseID field

Send a provideValidationFeedback request

At the end of a series of validations, Google recommends making a call to the Provide Validation Feedback API to indicate the final outcome of all the validations. The request sets two fields:

• conclusion — Indicates the validation version you used in your service, whether it was the one provided by the user, or the one returned from the Address Validation API.
• responseId — Indicates the response ID of the first response from the Address Validation API. See Set the previousResponseId field below.

Use either the provideValidationFeedback method (REST) or ProvideValidationFeedback method (gRPC).

The following example passes a JSON body to the request defining the conclusion:

curl -X POST -d '{
  "conclusion": "VALIDATED_VERSION_USED",
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:provideValidationFeedback?key=API_KEY"

• The conclusion field identifies one of the following actions from your side:
  • VALIDATED_VERSION_USED: the validated version of the address from the Address Validation API.
  • USER_VERSION_USED: the original version provided by the user.
  • UNVALIDATED_VERSION_USED: a version that was a result of a prompt to the user, but did not re-validate it with the Address Validation API.
  • UNUSED: abandoned the transaction.

See Validation Conclusion in the reference guide.

• The responseId field specifies which address validation results you are providing feedback for. This value must be the same as the responseId value returned by the first call to the validateAddress method.

See Request Body in the validation feedback reference guide.

Set the previousResponseID field

When issuing a follow-up request the Address Validation API for a given address, set the previousResponseId field.

• For the value of the previousResponseId, use the value from the responseId returned by API after the first validation request.
• Use this same value for any and all followup requests until the series completes.

This sequence diagram shows the preferred flow: