The Validate search type is optimized for users entering the complete address, as it would appear on an envelope. The entire address is submitted to the service, and a confidence is returned. The confidence corresponds to the degree of confidence in the returned address.

Methods

Validate can be used as a passive validation service that requires no user interaction after the initial search has been submitted by only accepting results of Verified confidence or as a interactive validation service.

Passive validation

  1. Enter a full address.
    • POST /address/validate/v1: A fully formatted address will be returned if a verified match to a single deliverable address was made.

Interactive validation

  1. Enter a full address.
    • POST /address/validate/v1: A fully formatted address will be returned if a verified match to a single deliverable address was made.
  2. Should the request not return a single deliverable address, request confirmation from the user for matches with Interaction required confidence.
  3. Should the response contain a list of suggestions that need further refinement, you can drill down further by stepping into a suggestion or providing a refinement.
    • GET /address/suggestions/stepin/v1/{global_address_key}: Step-in allows a user to select a suggestion and 'step into' it to obtain more detailed suggestions.
    • POST /address/suggestions/refine/v1/{global_address_key}: The user is able to provide additional information for the request, for example to select a single building from building numbers returned in a range.
  4. Repeat the above step as often as necessary until a full address is selected.
  5. Format the selected address, using the 'global address key'. You can choose between:
    • GET /address/format/v1/{global_address_key}: Formats an address into the standard 7 line global layout, thereby creating a well formatted address for every country and territory.
    • POST /address/format/v1/{global_address_key}: Formats an address into one of your available custom layouts.

Recommended implementations

There are three ways that this search type can be implemented into your solution. If an accurate match could not be found, the integrator can choose whether to return the address as it was entered by the user or to return a prompt requesting more user interaction.

The Validate search type may be used with no user interaction required after an initial search has been submitted. This allows an integrator to hide the fact that there is any address management occurring within an application from the user.
This implementation of using the Validate search type means that addresses that are entered will be simply verified as being correct (Verified match, Verified street or Verified place) or not verified as being correct (Interaction required or Multiple matches).

  1. The user types the address into separate fields.
  2. The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).
  3. The address entered will either be returned verified or not verified.

 Validation no user interaction sequence diagram

The recommended workflow (as demonstrated by our sample code) is:

validate no user interaction developer workflow

The relevant address components can be stored in your database if required.

The Validate search type may be used with minimal interaction required after an initial search has been submitted. This does not require the use of suggestions, but may require a single confirmation by the user if the service is not highly confident in the match.

This method of using the Validation engine means that addresses that are entered will either be:

  • Verified as being correct
  • Verified as being correct after user confirmation
  • Not verified as being correct
  1. The user types the address into separate fields.
  2. The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).
  3. The address will then either be:
    • A verified match. The matched address will be returned to the user.
    • More interaction required from the user to confirm the address is correct.
    • If address is not confirmed correct, the original entered address is presented as unverified.

 Validation minimal user interaction sequence diagram

The recommended workflow (as demonstrated by our sample code) is:

validate minimal user interaction developer workflow

The relevant address components can be stored in your database if required.

The Validate search type may be used with full user interaction after an initial search has been submitted. This will require the display and use of suggestions for searches that could not locate a single deliverable match.

This method of using the Validation engine means that addresses that are entered will either be:

  • Verified as being correct.
  • Verified as being correct after user confirmation.
  • Matched to one or more close addresses, which the user can interactively traverse.
  • Not verified.
  1. The user types the address into separate fields.
  2. The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).
  3. The address will then either be:
    • A verified match. The matched address will be returned to the user.
    • More interaction required from the user to confirm the address is correct.
    • Multiple address options available. Users can choose between a list of options to confirm an address.
    • If address is not confirmed correct, the original entered address is presented as unverified.

 Validation full user interaction sequence diagram

The recommended workflow (as demonstrated by our sample code) is:

validate full user interaction developer workflow

The relevant address components can be stored in your database if required.