Validating a Recipient

To try these examples, sign up for a free test account on Uniserv CONNECT and get your API key!

Basic Recipient Validation

The Recipient-Validation API enhances standard address validation by also checking whether the given recipient (or household) matches the address. Send a JSON POST to the /validate-recipient endpoint:

POST /location/v1/validate-recipient
Content-Type: application/json
Authorization: Bearer <your-api-key-here>

{
  "street": "Rastatter Str.",
  "houseNumber": "13",
  "postalCode": "75179",
  "locality": "Pforzheim",
  "country": "DE",
  "firstName": "Max",
  "lastName": "Mustermann"
}

You may also supply recipient instead of firstName/lastName if you prefer a single field:

{
  "street": "...",
  "houseNumber": "...",
  "postalCode": "...",
  "locality": "...",
  "country": "DE",
  "recipient": "Max Mustermann"
}

The service will:

Validate your API key and request format.
Run standard address validation (see Address Validation Data Model).
Call the recipient/household check (only for DE and if houseNumber present).
Return combined results with resultClassDetails.

Example Response

On success, you receive HTTP 200 and a JSON body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resultClass": "C",
  "resultClassDetails": {
    "addressResult": "A",
    "recipientResult": "B",
    "recipientLevel": "PERSON",
    "recipientAddressCorrection": []
  },
  "results": [
    {
      "addressType": "delivery",
      "country": "DE",
      "postalCode": "75179",
      "locality": "Pforzheim",
      "street": "Rastatter Str.",
      "houseNumber": "13",
      "firstName": "Max",
      "lastName": "Mustermann",
      "_meta": {
        "fields": {
          "firstName": { "relevance": "IMPORTANT", "status": "IDENTIFIED" },
          "lastName":  { "relevance": "MANDATORY", "status": "NORMALIZED" },
          "houseNumber": { "relevance": "IMPORTANT", "status": "IDENTIFIED" }
        }
      }
    }
  ]
}

Understanding the Results

resultClass – Overall quality (A–F) combining address and recipient checks.
addressResult – Address-only result class (A–F).
recipientResult – Recipient match result:
A: No change (exact match)
B: Only normalization (e.g., “mustermann” → “Mustermann”)
C: Changed (e.g., “mustermann” → “Musterfrau”)
F: Not identified
recipientLevel – Match level:
PERSON – Both first and last name matched
HOUSEHOLD – Only last name matched
NONE – No match or not checked
recipientAddressCorrection – House-number corrections by recipient check:
NONE
HOUSE_NUMBER_CORRECTED_BY_RECIPIENT
HOUSE_NUMBER_ADDED_BY_RECIPIENT

Field Reference

See detailed input/output fields: Recipient-Validation Data Model.

Troubleshooting

The API returns errors with HTTP status codes and a payload in problem+json format (see RFC 7807):

Example – missing or invalid auth:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
X-Uniserv-Request-Id: abcd1234

{
  "status": 401,
  "type": "https://docs.uniserv.com/location/problems#no-auth-data",
  "title": "No authorization header present"
}

For a full list of error types and solutions, see list of errors.