Build your validation logic

This document describes a process for building an address checking system to handle a variety of responses from the Address Validation API. It covers how to build your logic to correctly use the response, to investigate other signals from the API, and when and how to prompt your customers for more information.

In general the API response determines the following ways your system should handle an address:

• handyman Fix—the address is low quality. You should prompt for more information.
• edit Confirm—address is high quality, but has changes from the input address. You might prompt for confirmation.
• check Accept—address is high quality. You can accept the address provided.

Key purpose

This document helps you modify your system to best analyze the API response and determine the next actions to take with supplied addresses. The following pseudocode illustrates a possible flow.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

The exact logic depends on your situation - see Implementation guidance for more details. You can also use our open source implementation of this logic, which is in the Extended Component Library.

Workflow overview

The table below summarizes two actions for your system:

1. The workflow to use based on the fix, confirm, accept behavior.
2. The first signals to check for from the response. The signals described here come from the verdict property and are not the only signals to check for, but provide an initial indicator of the address quality. Each behavior type corresponds to a section in this document describing further signals you might also need to investigate.

Implementation guidance

When designing how your system responds to signals from the Address Validation API, the following recommendations can help you build a more effective response model. However, these are only recommendations, so bear in mind that your implementation should suit your business model.

Fix an address

Fix an address when the results clearly indicate that the address is not deliverable. Your system can then prompt the customer to provide the necessary information, after which you re-issue your workflow to get a deliverable address.

Fix signals

The Address Validation API provides a number of signals to let you know if an address should be fixed.

1. Validation granularity and missing components

These two signals provide the best indication of a problematic address:

• Whenever the validationGranularity field is OTHER, your system should investigate address component signals to learn more about where the error occurred and how to fix it.
• Whenever the post-processed address object returns a missingComponentTypes field, your system should check for that component. Missing components also render an address incomplete and non-deliverable.

2. Other signals

The Address Validation API also provides the other signals to help diagnose specific issues:

3. US address signals

Certain fields applicable only to US addresses provide a useful signal that the address is not deliverable and should be fixed. For an address that requires fixing, you should see the following:

For details on dpvConfirmation, see Handle United States addresses.

Fix address examples

Confirm an address

You confirm an address when the verdict indicates that the Address Validation API either inferred or made changes to address components in order to produce a validated address. In these cases, you have a deliverable address, but prefer greater confidence that the resulting address is the one intended by the customer.

To provide the customer with the correct prompting, your logic would identify the components flagged by the service to determine which action or flag the API applied to the component, such as inferred, replaced, or spellCorrected. See AddressComponent in the reference.

Confirm signals

The Address Validation API provides a number of signals to let you know if an address should be confirmed.

1. Validation Granularity

A validationGranularity of ROUTE or better is acceptable, but either PREMISE or SUBPREMISE provides a stronger signal of deliverability.

2. Other signals

When deciding to confirm address entry with the customer, the verdict also provides the following to determine what components to investigate:

3. US address signals

Certain fields applicable only to US addresses indicate that your logic should confirm details with the customer. Either of the following apply:

Confirm address examples

Accept an address

You accept an address when the verdict provides a high degree of confidence that the address is deliverable and can be used without further customer interaction in the downstream process.

Accept signals

The Address Validation API provides a number of signals to let you know if an address should be confirmed.

1. Validation Granularity

A validationGranularity of PREMISE or better is acceptable, but in some cases, ROUTE still indicates a deliverable address.

2. Other signals

A verdict for a high quality address should also provide the following:

• No replaced data. In this case, hasReplacedComponents: FALSE.
• No inferred components. In this case, hasInferredComponents: FALSE.

3. US address signals

Certain fields applicable only to US addresses indicate a high quality address that can be delivered to. For an acceptable US address, you should see the following:

Accept address examples