Address Verification & Validation Intelligence (AVVI)

Address Verification & Validation Intelligence (AVVI) combines address parsing and address validation.

Address parsing separates an extracted address into structured components, such as the street, city, and postal code, and normalizes their format.
- Normalization is part of parsing and rewrites the address in a consistent format.
Address validation checks the complete address against a selected data source to determine whether that source recognizes it as valid or deliverable.

Together, these capabilities produce consistent address data and help determine whether a Submission should continue through the flow or be routed for review.

Hyperscience provides an Address Validation Subflow that checks addresses with the Google Address Validation API. You can adapt the subflow to use your organization's reference data or another third-party service. This separation lets you change how addresses are verified without rebuilding how they are extracted.

Availability
Address parsing is available in v43.2 and later as a Document Processing Flow setting.
You can use the built-in parsers in SaaS, on-premise, and air-gapped deployments.
External parsing providers require outbound network access.
In v44.0 and later, Hyperscience provides an example Address Validation subflow that you can add to and adapt for your flow.
Contact your Hyperscience representative for the latest compatible version.

Differences between parsing and validation

Capability	Question it answers	Result	Where it runs
Address parsing and normalization	What parts make up this address, and how can they be represented consistently?	A normalized address and components such as recipient, street number, street name, unit, city, state or province, postal code, and country.	After Machine Transcription, Manual Transcription, or Flexible Extraction finishes an address field.
Address validation	Does an external address provider accept this address as written?	An `is_deliverable` value on each field processed by the example subflow.	After extraction and any human review, when the field values are final.

Why use AVVI

AVVI helps you structure address data, verify extracted addresses, and decide what should happen next in the flow.

Benefit	How AVVI helps
Validate the address as written	A `true` value confirms the address on the document, not a version that the provider corrected. For example, if the provider replaces the ZIP code, the value is `false`.
Stop address errors before they move downstream	With `is_deliverable` in the output, downstream logic can hold or route a submission before an incorrect address affects a shipment or another business process.
Validate human corrections	The subflow runs after Flexible Extraction, so it also validates addresses that keyers identify or correct.
Reuse validation in other flows	The subflow takes a submission as input and returns a submission as output. Add it to any flow that extracts addresses.
Get consistent address components without custom code	Address parsing returns the components of every address-typed field in the same format. You can compare addresses across documents and compare extracted addresses with Ground truth without adding custom parsing logic to each flow.

Best-fit scenarios

Use parsing and validation where structured or verified address data changes a downstream decision. The following examples show when to use parsing, validation, or both.

Scenario	Recommended capability	Outcome
A downstream system stores address components in separate fields.	Address parsing	The flow returns consistent components without custom parsing logic for each document type.
You compare addresses across an invoice, bill of lading, and rate confirmation.	Address parsing	Custom flow logic can compare normalized components instead of raw strings with different formatting.
You measure extraction results against ground truth.	Address parsing	Normalized components make differences easier to identify and explain.
A shipment must not continue when its delivery address is not accepted as written.	Address validation	Downstream logic can route `false` and `null` results for the appropriate follow-up.
A downstream system needs structured components and a deliverability decision for the same address.	Address parsing and address validation	The flow returns consistent components for the downstream system and an `is_deliverable` value for routing.
Your deployment has no outbound network access.	Address parsing with Local only (no external API)	The flow can structure address data, but it cannot verify deliverability against a current external address source.

Address parsing

Parsing process

Address parsing is a post-transcription process in the Document Processing Flow. It is off by default and applies to address-typed fields when you turn on Address Parsing Enabled.

Machine Transcription, Manual Transcription, or Flexible Extraction produces the final transcription for an address field.
The configured parser normalizes the address and separates it into components.
The flow adds the normalized value and parsed components to the block output and the transformed submission output.

Choose one of the following parsing providers:

Provider	When to use it	Requirements
Local only (no external API)	Use the built-in US and international parsers when address data must remain in your deployment, or the instance cannot connect to an external service.	No API key or outbound network access.
Google Address Validation API, Smarty US Extract API, or Geoapify Geocoding API	Use an external provider when its parsing, normalization, geocoding, or provider-specific data meets your requirements.	An account and API key for the selected provider, outbound network access, and approval to send address data to that provider.

All providers return a common set of address components. A component that the parser cannot find is null. An external provider can also return provider-specific information. For example, Google can return latitude and longitude.

Prerequisites

Required: address-typed fields in the layout for the addresses you want to parse.
Required for an external provider: an account and API key for the provider, outbound network access, and approval to send address data to that provider.
Recommended for the built-in international parser: capacity for its additional memory and start-up time. See Requirements and limitations.

Set up address parsing

Configure parsing in the Document Processing Flow settings.

Go to Flows, and then edit the flow.
In Flow Studio, select Address Parsing from the Settings Type drop-down list.
Turn on Address Parsing Enabled.
In Address Parsing Provider, select Local only (no external API), Google Address Validation API, Smarty US Extract API, or Geoapify Geocoding API.
If you select an external provider, enter the API Key and any required Provider Options.
Click Save.

After the flow processes an address-typed field, inspect the applicable transcription or Flexible Extraction Block output for the normalized address and parsed components. For the complete settings reference, see Document Processing Flow.

Address validation

Validation process

Hyperscience provides the Address Validation subflow as an example that you can add to and adapt for a flow. It is not a built-in Document Processing Flow block. The subflow accepts a submission, evaluates the configured address fields, adds a result to each field, and returns the updated submission.

The Document Processing Flow finishes extracting the address fields and completes any applicable human review.
The subflow sends each field listed in Address Fields to Validate to the configured validation provider.
The provider evaluates the complete address string.
The subflow adds is_deliverable to the field and returns the submission so later blocks and downstream integrations can use the result.

Provider used by the example
The example subflow uses the Google Address Validation API. Google is not required for every address-validation flow. A flow developer can adapt the subflow to use another validation provider.

Interpret validation results

The result indicates whether the configured provider accepted the address as written. It does not replace your organization's routing or review rules.

`is_deliverable` value	Meaning	Recommended handling
`true`	The provider accepts the address as written on the document.	Continue according to your business rules.
`false`	The provider rejects the address, recommends review, or accepts it only after correcting or replacing part of it.	Route the submission for review or apply your organization's exception logic. Do not interpret `false` only as “the location does not exist.”
`null`	The subflow did not receive a result for the field. The submission continues to process.	Handle the missing result separately from a failed validation.

Prerequisites

Required: the Address Validation subflow. Contact your Hyperscience representative for the latest compatible version.
Required for the supplied implementation: a Google Maps Platform API key with the Address Validation API enabled.
Required: outbound connectivity from the instance to the configured validation provider.

Set up address validation

Start with the latest compatible version of the example Address Validation subflow. Before you add it to a production flow, confirm the provider, fields, routing rules, and error handling with the flow owner.

Configure the following values in the supplied subflow:

Setting	Description
Address Fields to Validate	The fields whose complete address strings the subflow sends to the provider.
Google Address Validation API key	The Google Maps Platform credential used by the example subflow.

Test the flow with accepted addresses, addresses that require correction, unrecognized addresses, and simulated provider failures. Confirm that each result follows the routing and exception-handling rules defined for your process.

Example layout included in the Address Validation package
The supplied Address Validation package includes an example layout named Address Document. It contains Bill To Address and Ship To Address fields that capture each complete postal address as one string.
The example demonstrates one way to prepare invoice addresses for validation. The field names, layout type, and extraction instructions are not requirements of the Address Validation subflow. Adapt the layout and the fields selected for validation to your document types and business rules.

Requirements and limitations

Review these requirements and limitations before you use address parsing or validation in a production flow.

Requirement or limitation	Description
Parsing and validation do not fix extraction errors	If the flow identifies the wrong address, combines nearby text, or omits part of an address, parsing can expose the problem in the components and validation can reject the value. Neither capability guarantees a corrected extraction.
Validation requires an external provider	The provider maintains the address data used to evaluate deliverability. Air-gapped deployments cannot use address validation.
External providers receive address data	Addresses can contain personal data. Review your security, privacy, data-residency, and Vendor requirements before you configure an external provider.
External services can add cost and processing time	Review the selected provider's pricing, quotas, throughput, and error handling before production use.
Parsed components are not written to the Hyperscience database	They are available at runtime in the applicable block output and in the transformed submission output.
The built-in international parser requires additional resources	Its first run can take 2–3 minutes to start, and it can require approximately 1 GB of additional memory on the machine that runs it. The international model loads only when the US parser cannot parse an address.
A validation result is one input to a business decision	Define how the flow handles `false`, `null`, provider errors, and suggested corrections before you use the result to stop or continue a business process.