Address Verification

What it does

POST /address/verify checks a person (first name, last name, date of birth) against a postal address. It returns a match level, a score from 0 to 100, the address in its confirmed form and a decision: OK, REVIEW or NOK.

It answers "does this person live at this address", not "does this address exist". A valid address with the wrong person on it scores low.

Coverage. The service verifies addresses internationally. DE and AT are handled by the primary postal source, which also corrects addresses. All other countries are handled by the international source. Switzerland (CH) is a current limitation, see Which source answers.

Base URL: see Environments. Authenticate as described in Authentication. The full schema is in the Umbrella API reference.

Request

{
  "country": "DE",
  "address": {
    "street": "Musterstrasse",
    "number": "12",
    "zip": "10115",
    "city": "Berlin"
  },
  "identity": {
    "firstname": "Erika",
    "lastname": "Mustermann",
    "dob": "1985-04-12"
  }
}

Country handling. DE, AT and CH are recognised in both forms (DEU, AUT, CHE are converted). Any other value is passed on as sent, so send a valid ISO 3166-1 code.

A key repeated anywhere in the JSON body is rejected with 400.

Known issue. The service does not check the body for missing fields. A request without a required field ends in a 500 instead of a 400. Send every required field.

Which source answers

Each request is answered by exactly one source, chosen by country. The routing is fixed and not configurable per account.

There is no fallback: if the selected source cannot be reached or fails, the call ends in a 500 and no second source is tried. Retry later; a failed call is not a NOK and says nothing about the person.

Access is per account: an account without the service gets 403, and an account with a transaction limit gets 429 once the limit is used.

Response

{
  "inputAddress": "Musterstrasse 12, 10115, Berlin, DEU",
  "correctedAddress": "Musterstraße 12, 10115, Berlin, DEU",
  "finalAddress": "Musterstraße 12, 10115, Berlin, DEU",
  "addressStatus": "corrected",
  "addressComponents": {
    "street": "Musterstraße",
    "number": "12",
    "zip": "10115",
    "city": "Berlin",
    "country": "DEU"
  },
  "matchQuality": "EXACT",
  "score": 95,
  "globalResult": { "overall": "OK", "totalScore": 95 },
  "identity": { "fullName": "Erika Mustermann", "dob": "1985-04-12" },
  "extendedMessage": "addressCorrected"
}

ERROR is listed in the schema as a value of globalResult.overall but the service never returns it. Failures are HTTP errors.

matchQuality

HOUSENUMBER_MATCH is in the schema and appears only in the sandbox test cases.

Decision logic

The decision is a fixed mapping from the source's result to a score, a matchQuality and overall. There is no threshold you can configure, and no weighting of fields you can change.

Scores are not continuous. Use overall for the decision and score to rank or report.

DE and AT: score by source result

A timeout reported by the source is returned as a NOK with an empty extendedMessage and is not distinguishable from a real non-match except by that empty message. Pending verification: whether the source also fails the HTTP call in that case.

Other countries: name score times address score

The international source reports which parts matched. The service turns them into two sub-scores, multiplies them and maps the result.

Address score

Name score

Combination. address score × name score ÷ 100 is rounded to the nearest ten (a value of exactly 100, 95 or 25 is kept), anything below 25 becomes 0, and anything between 25 and 50 becomes 25. The result maps as follows.

On a 25 the message is an address-level label and can be one of the address messages above or a plain word such as Full. Read it as informational. A full name match with a wrong date of birth scores 20 on the name, which brings the result to 0 or 25 whatever the address: a verified address does not rescue a contradicted date of birth.

Reason codes

extendedMessage explains a result. The code is stable enough to log and show to an agent. It is not a contract for automation: new codes can appear and an empty string is normal, so branch on globalResult.overall.

The schema also lists skippedDOB; the service never sets it.

Errors

Error bodies are JSON. Their shape varies by cause.

Pending verification: how an invalid or expired token is reported. The service can answer 500 with the token library's message instead of 401.

Sandbox

The sandbox does not call any source. It answers from nine fixed test cases and returns the same response shape. It is authenticated like production.

A request is matched on all of country, street, number, zip, city, the full name and dob, exactly as written. DEU, AUT and CHE are accepted for the country.

These are test records, not real customers. Send firstname and lastname as the two words of the name.

Differences from production:

• extendedMessage holds the case description, for example Full match or No match, not a reason code.
• addressStatus and the address lines come from the test case. The country in them is two letters (AT), not three.
• A request that matches no case still returns 200, with {"success": false, "message": "Test Case Mismatch (Case ID: ...)"} listing which fields differ from the closest case. The message is a string, not the response shape above. Check for success before reading the fields. If nothing is close, the message starts with Critical Failure.
• Only AT, DE and CH have test cases. There is no case for other countries, and none that returns HOUSEHOLD_MATCH or NO_MATCH through the international source.

Mock

This portal serves canned answers that need no token and no account, so you can build a client first. They are not the sandbox: the body is not computed from your request.

POST /mock/api/services/address/verify returns the OK example above. Add ?scenario=review for a REVIEW and ?scenario=no-match for a NOK. ?scenario=bad-request and ?scenario=unauthorized return the error shapes from the schema. See Environments.

Worked examples

OK

The request and response at the top of this page: Germany, address corrected, score 95.

REVIEW

Spain, answered by the international source. City and post code match, the street does not.

{
  "inputAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "correctedAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "finalAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "addressStatus": "unchanged",
  "addressComponents": {
    "street": "Calle Ejemplo",
    "number": "5",
    "zip": "28001",
    "city": "Madrid",
    "country": "ES"
  },
  "matchQuality": "CITY_MATCH",
  "score": 50,
  "globalResult": { "overall": "REVIEW", "totalScore": 50 },
  "identity": { "fullName": "Juan Ejemplo", "dob": "1990-07-23" },
  "extendedMessage": "cityMatch"
}

NOK

Same request, but nothing matched.

{
  "inputAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "correctedAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "finalAddress": "Calle Ejemplo 5, 28001, Madrid, ES",
  "addressStatus": "unchanged",
  "addressComponents": {
    "street": "Calle Ejemplo",
    "number": "5",
    "zip": "28001",
    "city": "Madrid",
    "country": "ES"
  },
  "matchQuality": "NO_MATCH",
  "score": 0,
  "globalResult": { "overall": "NOK", "totalScore": 0 },
  "identity": { "fullName": "Juan Ejemplo", "dob": "1990-07-23" },
  "extendedMessage": "noMatch"
}

For a NOK from DE or AT, addressComponents can hold empty strings and finalAddress can be made of separators only, because no address was confirmed. Fall back to inputAddress.

Limits

• Per-account choice of source and a second-source fallback are not available at present.
• Pending verification: behaviour of the production routes against a live source. This page is written from the service code, not from live calls.