> ## Documentation Index > Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt > Use this file to discover all available pages before exploring further. # Address Verification > Address Verification API Documentation # 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](/api-reference/endpoint/addressVerification_address_verify). ## 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](../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 | Header | Value | | ------------- | ------------------------ | | Content-Type | `application/json` | | Authorization | `Bearer yourAccessToken` | ### Request Body Parameters | Field | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------------------------------------------------ | | country | string | Yes | ISO 3166-1 Alpha-2/Alpha-3 country code (e.g., DE, AT, ES). | | address.street | string | Yes | Street name. | | address.number | string | Yes | House or building number. | | address.zip | string | Yes | Zip or post code. | | address.city | string | Yes | Town or city name. | | address.province | string | No | District, province, or state. | | identity.firstname | string | Yes | First name of the person. | | identity.lastname | string | Yes | Last name of the person. | | identity.dob | string | Yes | Date of birth in the format `YYYY-MM-DD`. | | phone.phonenumber | string | No | Phone number in international format without special characters like "+" | ### Response Structure | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | inputAddress | string | Raw address provided. | | correctedAddress | string | Corrected version of the address. | | finalAddress | string | Final confirmed address. | | addressStatus | string | Status after verification (`corrected`, `unchanged`). | | addressComponents | object | Detailed components of the final address. | | matchQuality | string | Match level (`EXACT`, `HOUSEHOLD_MATCH`, etc.). | | score | integer | Confidence score (0-100). | | globalResult | object | Overall operation status (`OK`, `NOK`, `REVIEW`, `ERROR`). | | identity | object | Details of the identity as found in the search. | | extendedMessage | string | Detailed feedback. Enum: addressCorrected, postCodeMatch, localityMatch, cityMatch, districtMatch, previousAddress, incorrectAddress, identityNotFound, deceased, addressFakeSuspicion, noMatch, skippedDOB. | ### Match Quality Table | Match Quality | Description | | ------------------ | -------------------------------------------------------------------------------- | | EXACT | All input matches perfectly. | | HOUSEHOLD\_MATCH | Household-level match found. | | PARTIAL\_MATCH | Not all inputs matched perfectly but a number of inputs match. Review suggested. | | HOUSENUMBER\_MATCH | House/building number matches, others may not. | | STREET\_MATCH | Street-level match. | | CITY\_MATCH | Zip, district, or city-level match. | | IDENTITY\_MISMATCH | Matched at zip, district or city level; useful for regional approximations. | | NO\_MATCH | No person or address match found. | ### Global Result Table | Global Result | Description | | ------------- | ----------------------------------------------------- | | OK | Verification successful. All details match correctly. | | NOK | Verification failed. Mismatched or invalid data. | | REVIEW | Verification requires manual review. | | ERROR | Verification failed due to a system or input error. | ### Extended Message Table | Message | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | addressCorrected | Address matched after applying corrections to the format. | | postCodeMatch | Identity matched at the postcode level only. | | localityMatch | Identity matched at locality level only. | | cityMatch | Identity matched at city level only. | | districtMatch | Match found only at district level. | | NoCity | High probability person match on a real address, but incorrect City provided, rest of the address was correct. | | NoStreet | High probability person match on a real address, but incorrect Street provided, rest of the address was correct. | | NoPostCode | High probability person match on a real address, but incorrect Postcode provided, rest of the address was correct. | | previousAddress | Address linked to person’s previous residence. | | incorrectAddress | Identity matched, but address does not belong to them. | | addressFound | Address is formally correct but no personal link found. | | identityNotFound | Identity cannot be found at the given address. | | deceased | Person is likely deceased, matched against death table. | | addressFakeSuspicion | Address flagged as potentially fake. | | noMatch | Neither person nor address matched. | | skippedDOB | DOB check skipped due to missing source data. | | dobPartial | DOB details only partially matched, could be incorrect date, month, or year. | | dobFailedFull | DOB details - day, month, and year, did not match database. | | lastNameOnly | Only lastname/surname was matched. | | firstNameOnly | Only first name was matched. | ### Example Request ```json theme={null} { "country": "AT", "address": { "street": "Kampgasse", "number": "9", "zip": "3492", "city": "Etsdorf", "province": "" }, "identity": { "firstname": "Joe", "lastname": "Cardholder", "dob": "1970-12-01" }, "phone": { "phonenumber": "+43123456789" } } ``` ### Example Response ```json theme={null} { "inputAddress": "Kampgasse 9, 3492, Etsdorf, AT", "correctedAddress": "Kampgasse 9, 3492 Etsdorf, AT", "finalAddress": "Kampgasse 9, 3492 Etsdorf, AT", "addressStatus": "unchanged", "addressComponents": { "street": "Kampgasse", "number": "9", "zip": "3492", "city": "Etsdorf", "country": "AT" }, "matchQuality": "EXACT", "score": 100, "globalResult": { "overall": "OK", "totalScore": 100 }, "identity": { "fullName": "Joe Cardholder", "dob": "1970-12-01" }, "extendedMessage": "Full match" } ``` ## 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](/api-reference/endpoint/addressVerification_address_verify) ### Input Table | Test Case | Description | Street | Number | ZIP | City | Country | First Name | Last Name | DOB | | --------- | -------------------- | --------------------- | ------ | ----- | ------------- | ------- | ---------- | ---------- | ---------- | | 1 | Full match | Kampgasse | 9 | 3492 | Etsdorf | AT | Joe | Cardholder | 1970-12-01 | | 2 | Corrected full match | Billrothstr. | 39/16 | 1190 | Wien | AT | Wilma | Wohndtort | 1998-03-05 | | 3 | Street number match | Billrothstraße | 39 | 1190 | Wien | AT | Wilma | Wohndtort | 1998-03-05 | | 4 | Street level match | Billrothstraße | 3/16 | 1190 | Wien | AT | Wilma | Wohndtort | 1998-03-05 | | 5 | Postcode match | Döblinger Hauptstraße | 4/1 | 1190 | Wien | AT | Wilma | Wohndtort | 1998-03-05 | | 6 | No match | Edlinger Hauptstraße | 12/7 | 12345 | Berlin | DE | Hans | Dampf | 1998-03-05 | | 7 | Identity not found | Seegasse | 1 | 1000 | Lachen/Zürich | CH | Hubert | Spion | 1901-01-01 | | 8 | ZIP corrected | Kampgasse | 9 | 3496 | Etsdorf | AT | Joe | Cardholder | 1970-12-01 | | 9 | Household match | Kampgasse | 9 | 3492 | Etsdorf | AT | Jane | Cardholder | 1970-12-01 | ### Output Table | Test Case | Final Address | Address Status | Match Quality | Score | Overall Result | | --------- | ------------------------------------------- | -------------- | ------------------ | ----- | -------------- | | 1 | Kampgasse 9, 3492, Etsdorf, AT | unchanged | EXACT | 100 | OK | | 2 | Billrothstraße 39/16, 1190 Wien, AT | corrected | EXACT | 95 | OK | | 3 | Billrothstraße 39, 1190 Wien, AT | unchanged | HOUSENUMBER\_MATCH | 80 | OK | | 4 | Billrothstraße 3/16, 1190 Wien, AT | unchanged | CITY\_MATCH | 50 | REVIEW | | 5 | Döblinger Hauptstraße 4/1, 1190 Wien, AT | unchanged | CITY\_MATCH | 50 | REVIEW | | 6 | Edlinger Hauptstraße 12/7, 12345 Berlin, DE | unchanged | NO\_MATCH | 25 | NOK | | 7 | Seegasse 1, 1000, Lachen/Zürich, CH | unchanged | NO\_MATCH | 0 | NOK | | 8 | Kampgasse 9, 3492, Etsdorf, AT | corrected | EXACT | 95 | OK | | 9 | Kampgasse 9, 3492, Etsdorf, AT | unchanged | HOUSEHOLD\_MATCH | 80 | OK | ## 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.