---
title: Address cleanse
summary: Cleans and classifies a caller-supplied address through the CorrectAddress vendor service and returns normalized fields, status flags, and a POSTNET barcode.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Services.CleanAddress
reference_type: package
operation_id: OP-CA-05
trigger: Caller invokes clsCleanAddress.CleanAddress(inLine1, inLine2, inCity, inState, inZip, inZip4, inMixedCase)
---

# Address cleanse

Address cleanse is the library's primary operation. It submits a caller-supplied address to the CorrectAddress vendor service, tolerates vendor call failures by falling back to a sentinel return code, decodes the vendor's USPS error-code string into human-readable descriptions, classifies the result as cleaned, unmatched, or multiple matches, and derives a POSTNET barcode when the returned check digit supports it.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CA-05 |
| **Trigger** | Caller invokes `clsCleanAddress.CleanAddress(inLine1, inLine2, inCity, inState, inZip, inZip4, inMixedCase)` |
| **Inputs** | `inLine1`, `inLine2`, `inCity`, `inState`, `inZip`, `inZip4`, `inMixedCase` |
| **Outputs** | `clsCleanAddressInfo` containing normalized address fields, USPS return code, error codes/descriptions, classification flags, and POSTNET barcode |
| **Primary components** | `clsCleanAddress.CleanAddress`, `clsCleanAddressInfo`, `CleanAddressSvc.clsCAServices` |
| **Entry point** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb` |

## Steps

1. Create a new `CleanAddressSvc.clsCAServices` proxy instance and set `AllowAutoRedirect = True` and `UseDefaultCredentials = True`.
2. Call the vendor `CleanAddress` operation, passing the seven input parameters and receiving over twenty by-reference output fields (normalized address lines, county, USPS return code, USPS error codes, firm name, urbanization, DPC, check digit, carrier route, and related fields).
   - On failure: if the SOAP call raises an exception (observed in production with malformed vendor XML), set `outUSPSReturnCode = -999` instead of propagating the exception to the caller, per [BR-003](../business-rules.md#br-003-vendor-exception-fallback).
3. Parse the vendor's concatenated `outUSPSErrorCodes` string into a list of two-character codes, and resolve each code to a fixed description using a hardcoded lookup table from the vendor's CorrectAddress user manual (version 9.0, page C-2).
   - If code `11` is present, set the internal `HaveCode11` flag used in step 4.
   - If a code does not match a known entry, describe it as `"<code> - Code description not available"`.
4. Classify the address as cleaned according to [BR-001](../business-rules.md#br-001-cleaned-address-classification): the address is cleaned when `USPSReturnCode = 1`, or when `USPSReturnCode = -1` and error code `11` was not present.
5. When the address is not cleaned, classify it as unmatched or multiple matches according to [BR-002](../business-rules.md#br-002-unmatched-versus-multiple-match-classification):
   - If `USPSReturnCode` is `-1`, `-99`, or `-999`: set `Unmatched = True`.
   - Otherwise: set `MultipleMatches = True`.
6. Derive the POSTNET barcode according to [BR-005](../business-rules.md#br-005-postnet-barcode-derivation):
   - If the returned check digit is a single numeric character (`0`–`9`): concatenate the 5-digit ZIP, the 4-digit ZIP+4 extension (when present), the 2-character DPC (when present), and the check digit itself into the barcode string.
   - Otherwise: leave the barcode empty.
7. Return a new `clsCleanAddressInfo` populated with the normalized city, county, county code, address lines, state, ZIP, ZIP+4, the parsed USPS error codes and descriptions, the USPS return code, the derived POSTNET barcode, and the three classification flags (`CleanedAddress`, `Unmatched`, `MultipleMatches`).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller invokes CleanAddress]) --> Proxy[Create clsCAServices proxy]
	Proxy --> Call[Call vendor CleanAddress]
	Call --> Exception{Exception raised?}
	Exception -->|Yes| Fallback[Set USPS return code to -999]
	Exception -->|No| Parse[Parse USPS error-code string<br>into codes and descriptions]
	Fallback --> Parse
	Parse --> Classify{Cleaned address?<br>code 1, or -1 without code 11}
	Classify -->|Yes| Cleaned[CleanedAddress = True]
	Classify -->|No| Sub{Code -1, -99, or -999?}
	Sub -->|Yes| Unmatched[Unmatched = True]
	Sub -->|No| Multiple[MultipleMatches = True]
	Cleaned --> Barcode{Check digit numeric?}
	Unmatched --> Barcode
	Multiple --> Barcode
	Barcode -->|Yes| Derive[Derive POSTNET barcode]
	Barcode -->|No| Empty[Leave barcode empty]
	Derive --> Return([Return clsCleanAddressInfo])
	Empty --> Return
```

## Failure and edge-case behavior

- `CleanAddress()` converts service-call exceptions into return code `-999` and continues result classification instead of rethrowing, per [BR-003](../business-rules.md#br-003-vendor-exception-fallback).
- `-999` is treated as unmatched by [BR-002](../business-rules.md#br-002-unmatched-versus-multiple-match-classification), so a transport-level failure surfaces to the caller as a normal "unmatched" result rather than as an error.
- The POSTNET barcode is left empty whenever the check digit is not a single numeric character, without raising an error.
- USPS error codes not present in the hardcoded lookup table still produce a description (`"<code> - Code description not available"`) rather than failing.
- A commented-out block for reintroducing vendor-discarded "extraneous" address information into `Line2`/`Line1` remains in source but is not executed.*

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb`
- `Services\SAIF.Services.CleanAddress\clsCleanAddressInfo.vb`
- `Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb`