Workflow

Address and recipient validation consists of a sequence of steps. The following diagram is a simplified Workflow of the combined validation process with the most important steps, including the recipient/household check.

Figure 1. Address and Recipient Validation Workflow

Step Description

Step	Description
Search address	The first step is to search for all possible candidates that could match the input address. This is identical to Address-Validation: The API searches the database of known addresses (delivery, PO box, major-customer, etc.). If autocomplete is used, partial inputs return suggestions.
Evaluate address	After all possible address candidates have been found, they are evaluated to determine input quality. For example: Spelling variations of the street are considered. The system assigns a result class (A–F) that describes the address quality (→ Recipient result).
Enrich address	The chosen address (or list of candidates) can be enriched with optional data such as coordinates or ISO codes. Note: Some enrichment features may require a separate license. If a coordinate is requested and the house number changes later (in the recipient check), the coordinate might need to be recalculated.
Check recipient/household	After address enrichment, the Recipient-Validation verifies that the given recipient (first and last name) or at least the household (last name) matches the validated address. The check is made only if: * The address contains a house number. * The customer has enabled recipient validation. * The database can return: * `recipientResult` (A, B, C, or F) * `recipientLevel` (PERSON, HOUSEHOLD, NONE) * Any house-number corrections (`recipientAddressCorrection`) * If the response includes a house-number correction, that change is saved for the final result.
Return result	At the end of the workflow, the API combines the address validation result and the recipient/household result into a single response: * addressResult (from Evaluate address) * recipientResult, recipientLevel, and recipientAddressCorrection (from Check recipient/household) * The overall `resultClass` (A–F) is computed by considering both addressResult and recipientResult together. * The response JSON returns the corrected/normalized address, structured `firstName` and `lastName`, plus `_meta.fields` for every field. * For example, if the house number was corrected by the recipient check, `_meta.fields.houseNumber.status` shows `CHANGED`.

Search address

The first step is to search for all possible candidates that could match the input address.
This is identical to Address-Validation:
The API searches the database of known addresses (delivery, PO box, major-customer, etc.).
If autocomplete is used, partial inputs return suggestions.

Evaluate address

After all possible address candidates have been found, they are evaluated to determine input quality.
For example:
Spelling variations of the street are considered.
The system assigns a result class (A–F) that describes the address quality (→ Recipient result).

Enrich address

The chosen address (or list of candidates) can be enriched with optional data such as coordinates or ISO codes.
Note: Some enrichment features may require a separate license.
If a coordinate is requested and the house number changes later (in the recipient check), the coordinate might need to be recalculated.

Check recipient/household

After address enrichment, the Recipient-Validation verifies that the given recipient (first and last name) or at least the household (last name) matches the validated address. The check is made only if:
* The address contains a house number.
* The customer has enabled recipient validation.
* The database can return:
* recipientResult (A, B, C, or F)
* recipientLevel (PERSON, HOUSEHOLD, NONE)
* Any house-number corrections (recipientAddressCorrection)
* If the response includes a house-number correction, that change is saved for the final result.

Return result

At the end of the workflow, the API combines the address validation result and the recipient/household result into a single response:
* addressResult (from Evaluate address)
* recipientResult, recipientLevel, and recipientAddressCorrection (from Check recipient/household)
* The overall resultClass (A–F) is computed by considering both addressResult and recipientResult together.
* The response JSON returns the corrected/normalized address, structured firstName and lastName, plus _meta.fields for every field.
* For example, if the house number was corrected by the recipient check, _meta.fields.houseNumber.status shows CHANGED.