---
title: Client reference
summary: Complete reference for every contract operation this repository calls.
status: draft
owner: SAIF.Core documentation
last_reviewed: 2026-09-24
---

# Client reference

This page documents every operation of `clsCAServices` that repository source actually calls through `SAIF.Services.CleanAddressSvc.clsCAServices`, plus `HelloWorld`, which the contract declares but which no consumer in this repository calls.

---

## HelloWorld

`HelloWorld` is present in the `clsCAServices` contract ([`contract.md`](contract.md), declared operation 1) but is not called by any consumer in this repository — no in-repo source constructs or invokes it.

| Field | Value |
| --- | --- |
| **Operation** | `HelloWorld` |
| **SOAP action** | `http://tempuri.org/HelloWorld` |
| **Proxy member** | `string HelloWorld()` |
| **Input message** | None |
| **Output message** | `string HelloWorldResult` |
| **Declared faults** | None declared |
| **Called by** | Not called by any consumer in this repository |
| **Source** | `Services/SAIF.Services/Web References/CleanAddressSvc/clsCAServices.wsdl` |

This operation is documented for completeness because it is part of the declared contract; there is no call site, input binding, output handling, or fault-handling behavior to describe from repository source*.

---

## ConvertToProperCase

Converts a free-text string to proper case using the vendor engine behind `clsCAServices`*.

| Field | Value |
| --- | --- |
| **Operation** | `ConvertToProperCase` |
| **SOAP action** | `http://tempuri.org/ConvertToProperCase` |
| **Proxy member** | `string ConvertToProperCase(string inString)` |
| **Input message** | `ConvertToProperCaseSoapIn` |
| **Output message** | `ConvertToProperCaseSoapOut` |
| **Declared faults** | None declared |
| **Called by** | `SAIF.Services.Utilities.CleanAddress.CleanAddressService.ConvertToProperCase(string value)` (`Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:23`) |
| **Source** | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:23` |

### Input message — ConvertToProperCase

| Part | Type | Required | Bound from | Purpose |
| --- | --- | --- | --- | --- |
| `inString` | `string` | Not stated in the WSDL | `value`, the public method argument | The text to normalize |

### Output message — ConvertToProperCase

The returned string is trimmed and returned unchanged to the caller.

| Part | Type | Consumed by the caller | Notes |
| --- | --- | --- | --- |
| `ConvertToProperCaseResult` | `string` | Yes | `.Trim()` is applied before returning |

### Faults — ConvertToProperCase

| Fault | Surfaces as | Handled at the call site |
| --- | --- | --- |
| Generic SOAP fault | `SoapException` / `WebException` | Not handled — the exception propagates* |

### Call site — ConvertToProperCase

```csharp
result.Trim()
```

| Aspect | Finding |
| --- | --- |
| Invocation frequency | Per request* |
| Result cached | No |
| Timeout at this call site | None — `WebClientProtocol` default (100,000 ms) applies* |
| Retry at this call site | None |

### Notes — ConvertToProperCase
- A `null` result would throw `NullReferenceException` on `.Trim()`, and that possibility is not guarded*.

---

## CleanAddress

Sends a US address to the vendor address-cleansing engine and classifies the result as clean, unmatched, or a multiple-match, deriving a PostNet barcode from the returned fields.

| Field | Value |
| --- | --- |
| **Operation** | `CleanAddress` |
| **SOAP action** | `http://tempuri.org/CleanAddress` |
| **Proxy member** | `void CleanAddress(string inLine1, string inLine2, string inCity, string inState, string inZip, string inZip4, bool inMixedCase, ref string outLine1, ref string outLine2, ref string outCity, ref string outState, ref string outZip, ref string outZip4, ref string outCounty, ref string outCountyCode, ref int outUSPSReturnCode, ref string outUSPSErrorCodes, ref string outFirmname, ref string outUrbanization, ref string outLastLine, ref string outStringaddress, ref string outDPC, ref string outCheckdigit, ref string outCroute, ref string outLACS, ref string outLOTsequence, ref string outLOTcode, ref string outPMB, ref string outResults, ref string outStrnum, ref string outSecname, ref string outSecnum)` |
| **Input message** | `CleanAddressSoapIn` |
| **Output message** | `CleanAddressSoapOut` (via the same 25 `ref` parameters) |
| **Declared faults** | None declared |
| **Called by** | `SAIF.Services.Utilities.CleanAddress.CleanAddressService.CleanAddress(string addressLine1, string addressLine2, string city, string state, string zip, string zip4, bool mixedCase)` (`Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:57-60`) |
| **Source** | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressService.cs:57-60` |

### Input message — CleanAddress

| Part | Type | Required | Bound from | Purpose |
| --- | --- | --- | --- | --- |
| `inLine1`, `inLine2`, `inCity`, `inState`, `inZip`, `inZip4` | `string` | Not stated in the WSDL | Public method arguments | The address to clean |
| `inMixedCase` | `boolean` | Yes | Public method argument | Whether to preserve mixed case |
| 25 `out*` `ref` fields | `string` / `int` | Not stated in the WSDL | Local variables initialised to `""` / `0` (`CleanAddressService.cs:29-53`) | Echoed back by the service as output |

### Output message — CleanAddress

The caller reads `outUspsErrorCodes` through `CleanAddressErrorHelper.ParseErrors` and builds a `CleanedAddress` from `outLine1/2`, `outCity`, `outCounty`, `outCountyCode`, `outState`, `outZip`, `outZip4`, `outUSPSReturnCode`, and the parsed errors. It then derives three classification flags and a PostNet barcode (see [Business rules](business-rules.md)). Several returned fields are read into the response but never further used by any caller: firm name, urbanization, last line, string address, carrier route, LACS, LOT, PMB, results, street number, and secondary name/number.

| Part | Type | Consumed by the caller | Notes |
| --- | --- | --- | --- |
| `outLine1`, `outLine2`, `outCity`, `outState`, `outZip`, `outZip4`, `outCounty`, `outCountyCode` | `string` | Yes | Mapped into `CleanedAddress` |
| `outUSPSReturnCode` | `int` | Yes | Drives `IsAddressClean` / `IsUnmatched` / `HasMultipleMatches` classification — see [BR-CA-001](business-rules.md#br-ca-001-address-match-classification) |
| `outUSPSErrorCodes` | `string` | Yes | Parsed via `CleanAddressErrorHelper.ParseErrors` |
| `outDPC`, `outCheckdigit` | `string` | Yes | Used to build the PostNet barcode — see [BR-CA-002](business-rules.md#br-ca-002-postnet-barcode-construction) |
| `outFirmname`, `outUrbanization`, `outLastLine`, `outStringaddress`, `outCroute`, `outLACS`, `outLOTsequence`, `outLOTcode`, `outPMB`, `outResults`, `outStrnum`, `outSecname`, `outSecnum` | `string` | No | Returned by the service but not read by any caller in this repository |

### Faults — CleanAddress

| Fault | Surfaces as | Handled at the call site |
| --- | --- | --- |
| Generic SOAP fault or transport failure | Swallowed | A single `catch (Exception)` (CA1031 suppressed at `Services/SAIF.Services/GlobalSuppressions.cs`) sets `outUspsReturnCode = -999` and still returns a `CleanedAddress`; `IsUnmatched(-999)` is `true`, so a service outage is indistinguishable from a genuinely unmatched address |

### Call site — CleanAddress

```csharp
try
{
    UspsService.CleanAddress(addressLine1, addressLine2, city, state, zip, zip4, mixedCase,
            ref outAddressLine1, ref outAddressLine2, ref outCity, ref outState, ref outZip, ref outZip4, ref outCounty, ref outCountyCode, ref outUspsReturnCode, ref outUspsErrorCodes,
            ref outFirmname, ref outUrbanization, ref outLastLine, ref outStringaddress, ref outDpc, ref outCheckdigit, ref outCroute, ref outLacs, ref outLoTsequence, ref outLoTcode,
            ref outPmb, ref outResults, ref outStrnum, ref outSecname, ref outSecnum);
}
catch (Exception)
{
    outUspsReturnCode = -999;
}
```

| Aspect | Finding |
| --- | --- |
| Invocation frequency | Per request* |
| Result cached | No |
| Timeout at this call site | None — `WebClientProtocol` default (100,000 ms) applies* |
| Retry at this call site | None |

### Notes — CleanAddress
- The catch-all silently swallows every failure, not only "address not found" — see tech-debt finding TD-CA-01 in [Tech debt](tech-debt.md).

---

## FindCityStateInfoByZip

Resolves one or more city/state/county records for a ZIP code from a fixed-width result string.

| Field | Value |
| --- | --- |
| **Operation** | `FindCityStateInfoByZip` |
| **SOAP action** | `http://tempuri.org/FindCityStateInfoByZip` |
| **Proxy member** | `void FindCityStateInfoByZip(string inZIP, ref int outCount, ref string outString)` |
| **Input message** | `FindCityStateInfoByZipSoapIn` |
| **Output message** | `FindCityStateInfoByZipSoapOut` |
| **Declared faults** | None declared |
| **Called by** | `SAIF.Services.Utilities.CleanAddress.AddressSearchService.FindCityStateByZip(string zip)` → `Collection<ICleanedCityStateCounty>` (`Services/SAIF.Services/Utilities/CleanAddress/AddressSearchService.cs:21`) |
| **Source** | `Services/SAIF.Services/Utilities/CleanAddress/AddressSearchService.cs:21` |

### Input message — FindCityStateInfoByZip

| Part | Type | Required | Bound from | Purpose |
| --- | --- | --- | --- | --- |
| `inZIP` | `string` | Not stated in the WSDL | `zip`, the public method argument | The ZIP code to resolve |
| `outCount` | `int` (`ref`) | Not stated in the WSDL | Local variable initialised to `0` (`AddressSearchService.cs:18-19`) | Record count returned |
| `outString` | `string` (`ref`) | Not stated in the WSDL | Local variable pre-sized to `new string(' ', 50 * 55)` (`AddressSearchService.cs:19`) | Fixed-width result buffer |

### Output message — FindCityStateInfoByZip

The caller loops `outCount` times over 55-character records, reading City (chars 0–27, trimmed), State (chars 28–29), and County (chars 30–54, trimmed), and returns the collection.

| Part | Type | Consumed by the caller | Notes |
| --- | --- | --- | --- |
| `outCount` | `int` | Yes | Loop bound |
| `outString` | `string` | Yes | Parsed as fixed-width 55-character records |

### Faults — FindCityStateInfoByZip

| Fault | Surfaces as | Handled at the call site |
| --- | --- | --- |
| Generic SOAP fault | `SoapException` / `WebException` | Not handled — the exception propagates* |

### Call site — FindCityStateInfoByZip

```csharp
UspsService.FindCityStateInfoByZip(zip, ref outResultsCount, ref outResults);
```

| Aspect | Finding |
| --- | --- |
| Invocation frequency | Per request* |
| Result cached | No |
| Timeout at this call site | None — `WebClientProtocol` default (100,000 ms) applies* |
| Retry at this call site | None |

### Notes — FindCityStateInfoByZip
- Parsing assumes `outResultsCount * 55` fits inside `outResults`; a shorter string throws `ArgumentOutOfRangeException` from `Substring`*.

---

## RunCleanAddressBatch

Triggers a batch address-cleansing run against a file path and maps the returned code to a `BatchReturnType`.

| Field | Value |
| --- | --- |
| **Operation** | `RunCleanAddressBatch` |
| **SOAP action** | `http://tempuri.org/RunCleanAddressBatch` |
| **Proxy member** | `void RunCleanAddressBatch(string inPath, ref int outReturnCode)` |
| **Input message** | `RunCleanAddressBatchSoapIn` |
| **Output message** | `RunCleanAddressBatchSoapOut` |
| **Declared faults** | None declared |
| **Called by** | `SAIF.Services.Utilities.CleanAddress.CleanAddressBatchService.RunCleanAddressBatch(string inPath)` → `ICleanedAddressBatchResults` (`Services/SAIF.Services/Utilities/CleanAddress/CleanAddressBatchService.cs:20`) |
| **Source** | `Services/SAIF.Services/Utilities/CleanAddress/CleanAddressBatchService.cs:20` |

### Input message — RunCleanAddressBatch

| Part | Type | Required | Bound from | Purpose |
| --- | --- | --- | --- | --- |
| `inPath` | `string` | Not stated in the WSDL | `inPath`, the public method argument | The file path to process in batch |
| `outReturnCode` | `int` (`ref`) | Not stated in the WSDL | Local variable initialised to `0` | Batch outcome code |

### Output message — RunCleanAddressBatch

`returnCode` is mapped to `BatchReturnType` when `Enum.IsDefined`, otherwise `BatchReturnType.Unknown`, and returned as `CleanedAddressBatchResults { ReturnType, ReturnValue }`.

| Part | Type | Consumed by the caller | Notes |
| --- | --- | --- | --- |
| `outReturnCode` | `int` | Yes | Mapped to `BatchReturnType`, defaulting to `Unknown` for undefined values — see [BR-CA-003](business-rules.md#br-ca-003-batch-return-code-mapping) |

### Faults — RunCleanAddressBatch

| Fault | Surfaces as | Handled at the call site |
| --- | --- | --- |
| Generic SOAP fault | `SoapException` / `WebException` | Not handled — the exception propagates* |

### Call site — RunCleanAddressBatch

```csharp
UspsService.RunCleanAddressBatch(inPath, ref returnCode);
```

| Aspect | Finding |
| --- | --- |
| Invocation frequency | Per request* |
| Result cached | No |
| Timeout at this call site | None — `WebClientProtocol` default (100,000 ms) applies* |
| Retry at this call site | None |

### Notes — RunCleanAddressBatch
- The owning class is marked "Unsuppoted - converted over from VB code and only refactored for future reference" by its own author (`CleanAddressBatchService.cs:7-9`).

---

## Coverage checklist

| Operation | Documented section | Called by |
| --- | --- | --- |
| `HelloWorld` | [`HelloWorld`](#helloworld) | Not called by any consumer in this repository |
| `ConvertToProperCase` | [`ConvertToProperCase`](#converttopropercase) | `CleanAddressService.ConvertToProperCase` |
| `CleanAddress` | [`CleanAddress`](#cleanaddress) | `CleanAddressService.CleanAddress` |
| `FindCityStateInfoByZip` | [`FindCityStateInfoByZip`](#findcitystateinfobyzip) | `AddressSearchService.FindCityStateByZip` |
| `RunCleanAddressBatch` | [`RunCleanAddressBatch`](#runcleanaddressbatch) | `CleanAddressBatchService.RunCleanAddressBatch` |

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

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

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