---
title: SAIF.Services.CleanAddress business rules
summary: Enumerated business rules with per-rule trigger, enforcement, and outcomes.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-24
library: SAIF.Services.CleanAddress
reference_type: package
---

# SAIF.Services.CleanAddress business rules

This page captures business rules enforced by this library.

## BR-001: Cleaned address classification

| Field | Value |
| --- | --- |
| **Statement** | An address is treated as cleaned only when `USPSReturnCode = 1`, or when `USPSReturnCode = -1` and USPS error code `11` is not present. |
| **Trigger** | `CleanAddress()` finishes the vendor call and evaluates the returned USPS fields. |
| **Enforcement** | `clsCleanAddress.CleanAddress()` sets `m_CleanedAddress = True` only when the return-code test passes and `HaveCode11` is `False`. |
| **Outcome** | `clsCleanAddressInfo.CleanedAddress` is set to `True`; otherwise it remains `False`. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb` |

---

## BR-002: Unmatched versus multiple-match classification

| Field | Value |
| --- | --- |
| **Statement** | When an address is not cleaned, return codes `-1`, `-99`, and `-999` classify the result as unmatched; all other non-cleaned results classify it as multiple matches. |
| **Trigger** | `CleanAddress()` completes the cleaned-address evaluation. |
| **Enforcement** | `clsCleanAddress.CleanAddress()` sets `m_Unmatched = True` for `-1`, `-99`, or `-999`; otherwise it sets `m_MultipleMatches = True`. |
| **Outcome** | `clsCleanAddressInfo.Unmatched` and `clsCleanAddressInfo.MultipleMatches` become mutually exclusive status flags for non-cleaned results. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb` |

---

## BR-003: Vendor exception fallback

| Field | Value |
| --- | --- |
| **Statement** | Any exception raised during the vendor `CleanAddress` SOAP call is converted into USPS return code `-999` instead of being rethrown to the caller. |
| **Trigger** | The `Try/Catch` around `svc.CleanAddress(...)` catches an exception. |
| **Enforcement** | `clsCleanAddress.CleanAddress()` handles the exception and assigns `outUSPSReturnCode = -999`. |
| **Outcome** | Processing continues through the normal classification logic, which causes the result to be handled as unmatched by [BR-002](#br-002-unmatched-versus-multiple-match-classification). |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb` |

---

## BR-004: Batch return-code mapping

| Field | Value |
| --- | --- |
| **Statement** | Batch return codes map to normalized outcomes as follows: values greater than or equal to `0` become `Ok`, `-1` becomes `iniFileNotFound`, `-2` becomes `NoValidLicenseKey`, `-3` becomes `TrialExpired`, and all other values become `Unknown`. |
| **Trigger** | `RunCleanAddressBatch()` receives the vendor return code. |
| **Enforcement** | `clsCleanAddress.RunCleanAddressBatch()` applies a `Select Case ReturnCode` block and stores the mapped enum value in `clsBatchReturnInfo.BatchReturnValue`. |
| **Outcome** | Callers receive both the raw return code and the normalized `BatchReturnTypes` value. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb`<br>`Services\SAIF.Services.CleanAddress\mdlEnums.vb` |

---

## BR-005: POSTNET barcode derivation

| Field | Value |
| --- | --- |
| **Statement** | A POSTNET barcode is assembled only when the returned check digit is a single numeric character from `0` through `9`. |
| **Trigger** | `CleanAddress()` reaches the barcode-derivation block after address classification. |
| **Enforcement** | `clsCleanAddress.CleanAddress()` concatenates `outZip`, optional `outZip4`, optional `outDPC`, and `outCheckdigit` only when the check-digit test passes. |
| **Outcome** | `clsCleanAddressInfo.PostnetBarcode` contains the derived barcode string or remains empty when the check digit is invalid. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb` |

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [API reference](api/index.md)

## Sources
- `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb`
- `Services\SAIF.Services.CleanAddress\clsBatchReturnInfo.vb`
- `Services\SAIF.Services.CleanAddress\clsCleanAddressInfo.vb`
- `Services\SAIF.Services.CleanAddress\mdlEnums.vb`