Skip to main content

​
Address Verification API - Detailed Documentation

The Address Verification API is designed to support the management of address data by providing comprehensive address verification, validation, and cleansing functionalities.

​
API Playground:

You can try the address verify endpoint here.

​
Endpoints Overview

  1. Get Country Template: Retrieve required fields for address verification based on the country.
  2. Validate Address: Check if a given address exists and normalize it if necessary.
  3. Verify Address: Validate whether an individual can be matched to an address, including a match score, verification details, and handling corrections.
  4. Cleanse Address: Normalize and format an address to meet standard conventions.

​
Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.
  • Tokens are valid for 60 minutes and must be refreshed after expiration.
  • Refer to the Authentication for detailed steps on obtaining a token.
  • Include the token in the Authorization header as follows:
Authorization: Bearer YOUR_ACCESS_TOKEN

​
API Base URL

​
Production:

https://api-umbrella.io/api/services

​
Sandbox:

https://sandbox-umbrella-api.azurewebsites.net/api/services

​
1. Verify Address

​
Endpoints

POST /address/verify

​
Description

Verifies if an individual can be matched to a given address, including validation, a match quality score, and potential corrections.

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

FieldTypeRequiredDescription
countrystringYesISO 3166-1 Alpha-2/Alpha-3 country code (e.g., DE, AT, ES).
address.streetstringYesStreet name.
address.numberstringYesHouse or building number.
address.zipstringYesZip or post code.
address.citystringYesTown or city name.
address.provincestringNoDistrict, province, or state.
identity.firstnamestringYesFirst name of the person.
identity.lastnamestringYesLast name of the person.
identity.dobstringYesDate of birth in the format YYYY/MM/DD.

​
Response Structure

FieldTypeDescription
inputAddressstringRaw address provided.
correctedAddressstringCorrected version of the address.
finalAddressstringFinal confirmed address.
addressStatusstringStatus after verification (corrected, unchanged).
addressComponentsobjectDetailed components of the final address.
matchQualitystringMatch level (EXACT, HOUSEHOLD_MATCH, etc.).
scoreintegerConfidence score (0-100).
globalResultobjectOverall operation status (OK, NOK, REVIEW, ERROR).
identityobjectDetails of the identity as found in the search.
extendedMessagestringDetailed feedback. Enum: addressCorrected, postCodeMatch, localityMatch, cityMatch, districtMatch, previousAddress, incorrectAddress, identityNotFound, deceased, addressFakeSuspicion, noMatch, skippedDOB.

​
Match Quality Table

Match QualityDescription
EXACTAll input matches perfectly.
HOUSEHOLD_MATCHHousehold-level match found.
PARTIAL_MATCHNot all inputs matched perfectly but a number of inputs match. Review suggested.
HOUSENUMBER_MATCHHouse/building number matches, others may not.
STREET_MATCHStreet-level match.
CITY_MATCHZip, district, or city-level match.
IDENTITY_MISMATCHMatched at zip, district or city level; useful for regional approximations.
NO_MATCHNo person or address match found.

​
Global Result Table

Global ResultDescription
OKVerification successful. All details match correctly.
NOKVerification failed. Mismatched or invalid data.
REVIEWVerification requires manual review.
ERRORVerification failed due to a system or input error.

​
Extended Message Table

MessageDescription
addressCorrectedAddress matched after applying corrections to the format.
postCodeMatchIdentity matched at the postcode level only.
localityMatchIdentity matched at locality level only.
cityMatchIdentity matched at city level only.
districtMatchMatch found only at district level.
NoCityHigh probability person match on a real address, but incorrect City provided, rest of the address was correct.
NoStreetHigh probability person match on a real address, but incorrect Street provided, rest of the address was correct.
NoPostCodeHigh probability person match on a real address, but incorrect Postcode provided, rest of the address was correct.
previousAddressAddress linked to person’s previous residence.
incorrectAddressIdentity matched, but address does not belong to them.
addressFoundAddress is formally correct but no personal link found.
identityNotFoundIdentity cannot be found at the given address.
deceasedPerson is likely deceased, matched against death table.
addressFakeSuspicionAddress flagged as potentially fake.
noMatchNeither person nor address matched.
skippedDOBDOB check skipped due to missing source data.
dobPartialDOB details only partially matched, could be incorrect date, month, or year.
dobFailedFullDOB details - day, month, and year, did not match database.
lastNameOnlyOnly lastname/surname was matched.
firstNameOnlyOnly first name was matched.

​
Example Request

{
"country": "PL",
"address": {
  "street": "Doktora Jana Piltza",
  "number": "41",
  "zip": "30-392",
  "city": "Kraków",
  "province": ""
},
"identity": {
  "firstname": "Pawel",
  "lastname": "Ramski",
  "dob": "2001/10/25"
}
}

​
Example Response

{
  "inputAddress": "Doktora Jana Piltza 41 30-392 Kraków",
  "correctedAddress": "Piltza 41, 30-392 Kraków, Polska",
  "finalAddress": "Doktora Jana Piltza 41 30-392 Kraków",
  "addressStatus": "corrected",
  "matchQuality": "CITY_MATCH",
  "score": 50,
  "globalResult": {
    "overall": "REVIEW",
    "totalScore": 50
  },
  "identity": {
    "fullName": "Pawel Ramski",
    "dob": "2001/10/25"
  },
  "extendedMessage": "cityMatch"
}

​
Verification Test Cases

Please refer above for the Sandbox URL and endpoint to use, to try these test cases or try them in the API Playground here

​
Input Table

Test CaseDescriptionStreetNumberZIPCityCountryFirst NameLast NameDOB
1Full matchKampgasse93492EtsdorfATJoeCardholder1970-12-01
2Corrected full matchBillrothstr.39/161190WienATWilmaWohndtort1998-03-05
3Street number matchBillrothstraße391190WienATWilmaWohndtort1998-03-05
4Street level matchBillrothstraße3/161190WienATWilmaWohndtort1998-03-05
5Postcode matchDöblinger Hauptstraße4/11190WienATWilmaWohndtort1998-03-05
6No matchEdlinger Hauptstraße12/712345BerlinDEHansDampf1998-03-05
7Identity not foundSeegasse11000Lachen/ZürichCHHubertSpion1901-01-01
8ZIP correctedKampgasse93496EtsdorfATJoeCardholder1970-12-01
9Household matchKampgasse93492EtsdorfATJaneCardholder1970-12-01

​
Output Table

Test CaseFinal AddressAddress StatusMatch QualityScoreOverall Result
1Kampgasse 9, 3492, Etsdorf, ATunchangedEXACT100OK
2Billrothstraße 39/16, 1190 Wien, ATcorrectedEXACT95OK
3Billrothstraße 39, 1190 Wien, ATunchangedHOUSENUMBER_MATCH80OK
4Billrothstraße 3/16, 1190 Wien, ATunchangedCITY_MATCH50REVIEW
5Döblinger Hauptstraße 4/1, 1190 Wien, ATunchangedCITY_MATCH50REVIEW
6Edlinger Hauptstraße 12/7, 12345 Berlin, DEunchangedNO_MATCH25NOK
7Seegasse 1, 1000, Lachen/Zürich, CHunchangedNO_MATCH0NOK
8Kampgasse 9, 3492, Etsdorf, ATcorrectedEXACT95OK
9Kampgasse 9, 3492, Etsdorf, ATunchangedHOUSEHOLD_MATCH80OK

​
2. Get Country Template (Upcoming Service)

​
Description

Retrieve the required fields for address verification for a given country. Use this endpoint to ensure all mandatory fields are provided when performing address verification.

​
3. Validate Address (Upcoming Service)

​
Description

Validates if a given address exists. If corrections are necessary, the response includes both the original and corrected versions of the address.

​
4. Cleanse Address (Upcoming Service)

​
Description

Normalizes and formats an address to adhere to standard address conventions.