---
title: Business rules
summary: Rules enforced around the call to the remote service.
status: draft
owner: SAIF.Core documentation
last_reviewed: 2026-09-24
---

# Business rules

`CleanAddressService.CleanAddress` interprets the vendor's return code and error codes into caller-facing classification flags, and derives a PostNet barcode from returned fields; `CleanAddressBatchService.RunCleanAddressBatch` maps a raw return code to a typed enum. These are rules this repository enforces around the call, not rules the remote service documents.

---

## BR-CA-001 Address match classification

| Field | Value |
| --- | --- |
| Statement | An address is classified as clean when `outUSPSReturnCode` is `1`, or `-1` without USPS error code `"11"`; classified as unmatched when the return code is `-1`, `-99`, or `-999`; otherwise classified as having multiple matches |
| Trigger | After every `CleanAddress` call, including the swallowed-failure path that forces the return code to `-999` |
| Enforcement | `CleanAddressService.IsAddressClean`, `IsUnmatched`, `HasMultipleMatches` |
| Origin | call site |
| Outcome | Determines which of the three mutually exclusive classification properties is `true` on the returned `CleanedAddress`; no exception is thrown |
| Related operation | [`CleanAddress`](reference.md#cleanaddress) |
| Source | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:90-109` |

---

## BR-CA-002 PostNet barcode construction

| Field | Value |
| --- | --- |
| Statement | The PostNet barcode is built by concatenating ZIP, ZIP+4 (if 4 characters), delivery point code (if 2 characters), and a check digit; it is left empty when the check digit is not a single digit `0`–`9` |
| Trigger | After every `CleanAddress` call |
| Enforcement | `CleanAddressService.CleanAddress` |
| Origin | call site |
| Outcome | Populates `CleanedAddress.PostNetBarcode`, or leaves it empty when the check digit is invalid |
| Related operation | [`CleanAddress`](reference.md#cleanaddress) |
| Source | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:111-132` |

---

## BR-CA-003 Batch return code mapping

| Field | Value |
| --- | --- |
| Statement | The raw batch return code is mapped to a `BatchReturnType` enum value when the code is a defined member; otherwise it maps to `BatchReturnType.Unknown` |
| Trigger | After every `RunCleanAddressBatch` call |
| Enforcement | `CleanAddressBatchService.RunCleanAddressBatch` |
| Origin | call site |
| Outcome | Returns a `CleanedAddressBatchResults` with a typed `ReturnType`; an undefined code never throws, it degrades to `Unknown` |
| Related operation | [`RunCleanAddressBatch`](reference.md#runcleanaddressbatch) |
| Source | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressBatchService.cs:24-31` |

---

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Contract](contract.md)
- [Operation map](operation-map.md)
- [Client reference](reference.md)
- [Consumption](consumption.md)
- [Dependencies](dependencies.md)
- [Tech debt](tech-debt.md)

## Sources
- `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs`
- `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressBatchService.cs`