---
title: Batch address cleanse
summary: Launches a server-side batch address-cleansing run and normalizes the vendor's return code into a typed outcome.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Services.CleanAddress
reference_type: package
operation_id: OP-CA-02
trigger: Caller invokes clsCleanAddress.RunCleanAddressBatch(inPath)
---

# Batch address cleanse

Batch address cleanse hands a file path to the CorrectAddress vendor service so it can run a batch cleansing job server-side, then converts the vendor's raw integer return code into a typed `BatchReturnTypes` value the caller can branch on without memorizing vendor-specific codes.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CA-02 |
| **Trigger** | Caller invokes `clsCleanAddress.RunCleanAddressBatch(inPath)` |
| **Inputs** | `inPath` — path passed to the vendor batch operation |
| **Outputs** | `clsBatchReturnInfo` containing the normalized `BatchReturnValue` enum and the raw `ReturnValue` integer |
| **Primary components** | `clsCleanAddress.RunCleanAddressBatch`, `clsBatchReturnInfo`, `BatchReturnTypes`, `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 `RunCleanAddressBatch(inPath, ByRef ReturnCode)` on the proxy, passing the caller's file path and receiving the vendor's raw integer return code.
3. Map the raw return code to the `BatchReturnTypes` enum according to [BR-004](../business-rules.md#br-004-batch-return-code-mapping):
   - Any value `>= 0` maps to `Ok`.
   - `-1` maps to `iniFileNotFound`.
   - `-2` maps to `NoValidLicenseKey`.
   - `-3` maps to `TrialExpired`.
   - Any other value maps to `Unknown`.
4. Return a new `clsBatchReturnInfo` instance populated with both the normalized `BatchReturnValue` and the untouched raw `ReturnValue`.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller invokes RunCleanAddressBatch<br>with inPath]) --> Proxy[Create clsCAServices proxy]
	Proxy --> Call[Call vendor RunCleanAddressBatch<br>ByRef ReturnCode]
	Call --> Map{Map ReturnCode}
	Map -->|>= 0| Ok[BatchReturnTypes.Ok]
	Map -->|-1| Ini[BatchReturnTypes.iniFileNotFound]
	Map -->|-2| Lic[BatchReturnTypes.NoValidLicenseKey]
	Map -->|-3| Trial[BatchReturnTypes.TrialExpired]
	Map -->|other| Unk[BatchReturnTypes.Unknown]
	Ok --> Return([Return clsBatchReturnInfo])
	Ini --> Return
	Lic --> Return
	Trial --> Return
	Unk --> Return
```

## Failure and edge-case behavior

- Return codes outside the four explicitly handled cases map to `BatchReturnTypes.Unknown` per [BR-004](../business-rules.md#br-004-batch-return-code-mapping); this includes the enum's own sentinel value (`-1000000001`), which no vendor call is expected to return.*
- The vendor call is not wrapped in a `Try/Catch`; a SOAP fault or transport error propagates to the caller unhandled, unlike [Address cleanse](address-cleanse.md).*
- The caller always receives both the normalized enum and the untouched raw return code, so it can fall back to inspecting `ReturnValue` directly if `BatchReturnValue` is `Unknown`.

> **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\clsBatchReturnInfo.vb`
- `Services\SAIF.Services.CleanAddress\mdlEnums.vb`
- `Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb`