Validating a Recipient

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

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>

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

The API supports many more input variations, which are documented in the API reference. For example, you can pass first and last name in a single recipient field instead of using separate fields. However, no matter which input variant you use, the result structure is always the same.

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

{
  "recipient": "Max Mustermann",
  "addressLine": "Rastatter Str. 13",
  "postalCode": "75179",
  "locality": "Pforzheim",
  "country": "DE"
}

When Uniserv receives the request, it will do the following:

Check the address against its database of valid addresses
Correct the address in case of mistakes (wrong postal code, spelling mistakes, etc.)
Check the recipient or household (only for DE if an address was identified in step 2).
Enrich the address with additional information (if requested)
Return the corrected address and recipient (if possible) with an indication of the quality

In the best case (the address is valid without any errors), you will receive a result like this:

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" }
        }
      }
    }
  ]
}

Uniserv always returns a list of addresses, with resultClassDetails (see Recipient-Validation Data Model) and the resultClass attribute indicating the quality of the overall result:

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)

Requesting Additional Information

In addition to address validation, Uniserv can enrich the address with related information, like geo coordinates (longitude, latitude) or delivery information.

For example, we request coordinates based on the World Geodetic System (WGS, revision 84): see Validating an Address.

If you need field-by-field information on how well the input matched the returned candidates, you can request the metadata option:

    "_options": {
        "include": ["metadata"]
    }

Each candidate will then have a _meta attribute with additional information on each input field.

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.