services / location / cloud / 1.0 / recipient-validation

Data Model

The Recipient-Validation API checks and fixes addresses and also verifies that the given recipient (or household) matches the address. Right now, this service works only for Germany (DE).

The different address types and the individual address fields are explained on the Address-Validation Data Model page.

Address Fields

Below are only the extra fields used to check the recipient or household:

Field ( input) Length Type Description

recipient

50

string

The unstructured recipient name. This can be a single lastName (e.g., “Meier”) or “First Last” (e.g., “Max Mustermann”). Use this if you do not give firstName and lastName separately. Cannot be returned in the response.

firstName

50

string

The recipient’s firstName (structured).

lastName

50

string

The recipient’s lastName (structured).
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 JSON, you will see a block called resultClassDetails with four parts:

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

Address result

The result class for 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

A

No change (recipient found exactly; e.g., input “Meier” → output “Meier”)

B

Only normalization (e.g., “meier” → “Meier”)

C

Changed (name was corrected; e.g., “meier” → “Maier”)

F

Not identified (name not found or incomplete)

Recipient level

This shows what level matched:

Code Description

PERSON

Both first name and last name matched exactly.

HOUSEHOLD

Only household or last name matched (first name did not).

NONE

No match or check not done (for example, no house number).

Recipient Address Correction

This lists any changes to the house number (and thus the address) made during the recipient/household check:

Code Description

NONE

No changes made to the address.

HOUSE_NUMBER_CORRECTED_BY_RECIPIENT

House number was corrected by the recipient/household check.

HOUSE_NUMBER_ADDED_BY_RECIPIENT

House number was added by the recipient/household check.

If a house number was changed, that change appears in the final result. Also, _meta.fields.houseNumber.status will show CHANGED or IDENTIFIED, depending on the correction.

Meta-Information

Like in Address-Validation, each field under _meta.fields has relevance and status. We added firstName and lastName here:

  • relevance

    • MANDATORY – Required if you use firstName/lastName.

    • IMPORTANT – Important for the recipient check.

    • OPTIONAL – Only checked if provided.

  • status

    • IDENTIFIED – Value was recognized exactly.

    • NORMALIZED – Only small adjustments like case or accents.

    • CHANGED – The name was corrected.

    • NOT_IDENTIFIED – Could not find the value.

    • NOT_CHECKED – Field was not checked (for example, if recipient is used).

Example _meta block in the response:

"_meta": {
  "fields": {
    "lastName": {
      "relevance": "MANDATORY",
      "status": "IDENTIFIED"
    },
    "firstName": {
      "relevance": "IMPORTANT",
      "status": "IDENTIFIED"
    },
    "houseNumber": {
      "relevance": "IMPORTANT",
      "status": "IDENTIFIED",
      "changedByRecipient": true
    },
    …
  }
}

Here, changedByRecipient: true means the house number was changed by the recipient check.

Example Structure of the Full Result

In the response object, you will find these top-level fields in addition to the usual address fields:

  • firstName (structured first name)

  • lastName (structured last name)

  • resultClass (overall result that includes address and recipient)

  • resultClassDetails (detail block, see above)

  • results (array of candidates, like in Address-Validation, but with extra meta-info)

A shortened example:

{
  "firstName": "Max",
  "lastName": "Mustermann",
  "resultClass": "C",
  "resultClassDetails": {
    "addressResult": "D",
    "recipientResult": "A",
    "recipientLevel": "PERSON",
    "recipientAddressCorrection": ["HOUSE_NUMBER_CORRECTED_BY_RECIPIENT"]
  },
  "results": [
    {
      "firstName": "Max",
      "lastName": "Mustermann",
      "addressType": "delivery",
      "houseNumber": "50f",
      …
      "_meta": {
        "fields": {
          "lastName": {
            "relevance": "MANDATORY",
            "status": "IDENTIFIED"
          },
          "firstName": {
            "relevance": "IMPORTANT",
            "status": "IDENTIFIED"
          },
          "houseNumber": {
            "relevance": "IMPORTANT",
            "status": "IDENTIFIED",
            "changedByRecipient": true
          },
          …
        }
      }
    }
    // More candidates (only if resultClass = E)
  ]
}