---
title: Image retrieval
summary: Retrieves bill-image URLs and identifiers from the external ImagingAPI service for a claim's imaged documents.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim.Bill
reference_type: package
operation_id: OP-CB-07
trigger: Caller calls clsCallImageApi.GetImageUrlByTowId / GetImageTowId / GetImageUrl
---

# Image retrieval

Image retrieval is a thin wrapper over the external ImagingAPI client that resolves a bill image's URL or TOW (tracking/original-workflow) identifier for the claim document type group. It holds no local state beyond a lazily-created, cached API client and performs no database access of its own.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CB-07 |
| **Trigger** | Caller calls `clsCallImageApi.GetImageUrlByTowId(towId)`, `GetImageTowId(imageId)`, or `GetImageUrl(imageId)` |
| **Inputs** | `towId` or `imageId` |
| **Outputs** | Image URL string, TOW identifier, or a fallback empty/error value when the image is not found |
| **Primary components** | `clsCallImageApi.ClaimImageApiClient`, `clsCallImageApi.GetImageUrlByTowId`, `clsCallImageApi.GetImageTowId`, `clsCallImageApi.GetImageUrl` |
| **Entry point** | `Business\SAIF.Business.Claim.Bill\clsCallImageApi.vb` |

## Steps

1. **Resolve the imaging client (lazy singleton).** `ClaimImageApiClient` is created once and cached in a private field. It reads the imaging service endpoint from `EnvironmentService.GetConfigSetting("imagingApiUrl")` and constructs an `ImagingAPI.Client.ImagingClient` against that URL.

   > **Origin**: The `ImagingClient` type and its `GetImage`/`GetImageByTowId` calls are implemented by the external `ImagingAPI.Client` package. This dependency is not a same-repo library, so no per-operation page exists in this documentation set; see [Dependencies](../dependencies.md) for the package reference.
2. **Get an image URL by TOW ID.** `GetImageUrlByTowId(towId)` calls `ClaimImageApiClient.GetImageByTowId(DocTypeGroup.CLAIM, towId)`.
   - If the image is found: return `image.URL`.
   - If the API raises `NoMatchingDataException`: return `String.Empty`.
   - On any other exception: return the fallback string `"Error Occured getting link to image"`.
3. **Get a TOW ID by image ID.** `GetImageTowId(imageId)` calls `ClaimImageApiClient.GetImage(DocTypeGroup.CLAIM, imageId)`.
   - If the image is found: return `imageDetail.TowId`.
   - If the API raises `NoMatchingDataException`: return `0`.
   - On any other exception: return `-1`.
4. **Get an image URL by image ID.** `GetImageUrl(imageId)` calls `ClaimImageApiClient.GetImage(DocTypeGroup.CLAIM, imageId)`.
   - If the image is found: return `imageDetail.URL`.
   - If the API raises `NoMatchingDataException`: return `String.Empty`.
   - On any other exception: return the fallback string `"Error Occured getting image"`.
5. **Every lookup scopes to the claim document type group.** All three calls pass `DocTypeGroup.CLAIM`, so this class only ever resolves claim-scoped images, never other document type groups the underlying API may support.

## Process flow

The following diagram visualizes the three image-lookup entry points and their distinct not-found/error fallback values.

```mermaid
flowchart TD
	Start([Caller requests image data]) --> Which{Which lookup?}
	Which -->|By TOW ID| ByTow[GetImageByTowId<br>DocTypeGroup.CLAIM]
	Which -->|URL by image ID| UrlById[GetImage<br>DocTypeGroup.CLAIM]
	Which -->|TOW by image ID| TowById[GetImage<br>DocTypeGroup.CLAIM]
	ByTow --> ByTowFound{Found?}
	ByTowFound -->|Yes| ByTowUrl([Return image.URL])
	ByTowFound -->|NoMatchingDataException| ByTowEmpty([Return empty string])
	ByTowFound -->|Other error| ByTowErr([Return error link text])
	UrlById --> UrlFound{Found?}
	UrlFound -->|Yes| UrlOk([Return imageDetail.URL])
	UrlFound -->|NoMatchingDataException| UrlEmpty([Return empty string])
	UrlFound -->|Other error| UrlErr([Return error image text])
	TowById --> TowFound{Found?}
	TowFound -->|Yes| TowOk([Return imageDetail.TowId])
	TowFound -->|NoMatchingDataException| TowZero([Return 0])
	TowFound -->|Other error| TowNeg([Return -1])
```

## Failure and edge-case behavior

- Each method distinguishes only two outcomes beyond success: a specific `NoMatchingDataException` (image genuinely not found) and every other exception (treated as a generic error), with a different sentinel/message per method rather than a shared error contract.
- The "generic error" fallback values differ in type across methods — an empty string, a negative integer, or a descriptive error string — so callers must check per-method semantics rather than relying on a single uniform failure indicator.*
- The imaging endpoint is read from configuration once when the client is first constructed; a configuration change after the client has been created does not take effect without recreating the object.*

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.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

- `Business\SAIF.Business.Claim.Bill\clsCallImageApi.vb`