Data Model

The Recipient-Validation API checks and corrects addresses and also verifies that the given recipient (or household) matches the address. Right now, this service works only for Germany (DE). The first section, Address and Recipient Fields, gives you enough background on the data model to understand input and output of the API. The second section, Quality of an Address and Recipient, describes how to interpret the result in order to perform appropriate actions (e.g. automatic processing or manual post-processing).

Address and Recipient Fields

The different address types and the individual address fields are explained on the Address-Validation - Data Model page. This page only describes the additional fields for the recipient validation.

The following icons are used in the table to classify the fields:

This is an input field
This is an output field

Field Length Type Description

Field	Length	Type	Description
`recipient`	50	string	The unstructured recipient name. This can be a single last name (e.g., “Meier”) or first and last name of the recipient (e.g., “Max Mustermann”). Use this if you do can not give `firstName` and `lastName` separately.
`firstName`	50	string	The recipient’s firstName.
`lastName`	50	string	The recipient’s lastName.

recipient

string

The unstructured recipient name. This can be a single last name (e.g., “Meier”) or first and last name of the recipient (e.g., “Max Mustermann”). Use this if you do can not give firstName and lastName separately.

firstName

string

The recipient’s firstName.

lastName

string

The recipient’s lastName.

In one request, you must use either: The recipient field, the lastName field alone, or both firstName and lastName.
Do not combine recipient with firstName or lastName.

Quality of an Address and Recipient

In addition to normal address validation (see Address-Validation - Data Model), Recipient-Validation returns extra information that includes the recipient/household check.

In the response, you will see a block called resultClassDetails with four parts and the overall resultClass. This information provides an evaluation of the quality of the input.

"resultClass": "C",
"resultClassDetails": {
  "addressResult": "D",
  "recipientResult": "A",
  "recipientLevel": "PERSON",
  "recipientAddressCorrection": ["HOUSE_NUMBER_CORRECTED_BY_RECIPIENT"]
}

Result Class Details

Address result

The result class for "normal" address validation (addressResult) is exactly the same as in the Address-Validation service. You can see all codes (A, B, C, D, E, F) and their descriptions in the Address-Validation Data Model (Result classes).

Recipient result

The recipient/household check has its own result class codes. These codes show how well the name matched, with examples:

Code Description Example

Code	Description	Example
A	No change - `firstName` and `lastName` returned as-is	Input: Meier Output: Meier
B	Only normalization	Input: meier Output: Meier
C	Changed	Input: maier Output: Meier
F	Not identified (recipient not identified or not entered)	-

No change - firstName and lastName returned as-is

Input: Meier
Output: Meier

Only normalization

Input: meier
Output: Meier

Changed

Input: maier
Output: Meier

Not identified (recipient not identified or not entered)

Recipient level

This shows what level matched:

Code Description

Code	Description
PERSON	Both first name and last name matched exactly.
HOUSEHOLD	Only the recipient’s household (`lastName`) was identified.
NONE	No match or check not done.

PERSON

Both first name and last name matched exactly.

HOUSEHOLD

Only the recipient’s household (lastName) was identified.

NONE

No match or check not done.

Recipient Address Correction

All address changes that are performed AFTER normal address validation based on recipient check are defined here.

Code	Description
NONE	No changes performed to the address.
HOUSE_NUMBER_CORRECTED_BY_RECIPIENT	House number was corrected by the recipient check.
HOUSE_NUMBER_ADDED_BY_RECIPIENT	House number was added by the recipient check.

Code

Description

NONE

No changes performed to the address.

HOUSE_NUMBER_CORRECTED_BY_RECIPIENT

House number was corrected by the recipient check.

HOUSE_NUMBER_ADDED_BY_RECIPIENT

House number was added by the recipient check.

Result Class

The overall result resultClass is based on the results of the resultClassDetails described above.

A: perfect match; the address and the recipient is returned as-is
B: normalized match; some small syntactic fixes (i.e. case conversion)
C: corrected match; corrections with high confidence (i.e. fixed postal code based on street and house number)
D: probable match; corrections with lower confidence, but only one matching candidate address has been identified or the recipient was not identified
E: ambiguous match, returns a list of candidate addresses (no recipient check in this case)
F: no match; the address is invalid (no recipient check in this case)

Meta-Information

For each field, there can be the following detailed information about the quality of the single fields:

Relevance: The relevance field defines the importance of the field per address type and country.
Status: The status field describes for each field whether or how much the field has changed compared to the input.
unidentifiedElements: A list of tokens in that field that couldn’t be matched.

More information to the meta information can be read on the Address-Validation - Data Model page (see Meta Information).