---
title: Claim summary and detail retrieval
summary: Retrieves a single claim's full read-only header/detail view, or a worker's or policy's claim history, from the claim data API.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.View.Claim
reference_type: package
operation_id: OP-VC-01
trigger: Caller requests a claim by claim ID/number, or a worker/policy claim history, through `clsClaimData` or `clsClaimDataCollection`
---

# Claim summary and detail retrieval

This operation loads the read-only claim header used throughout claim-view screens and services. A caller either retrieves one claim by its identifier (`clsClaimData`) or retrieves a set of claim headers for a worker or policy (`clsClaimDataCollection`). Both paths populate the same `clsClaimData` shape from the same underlying claim-data API and add a handful of supplemental Oracle reads for values the API does not provide (active support-order count, MCO short description, total amount paid). Several claim-detail sub-areas — reserves, awards, beneficiaries, MCO history, EAIP data, vocational details — are lazily loaded from this object on first access and are documented as their own operations.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-VC-01 |
| **Trigger** | Caller calls `clsClaimData.GetData`/`GetDataAsync` with a claim ID or claim number, or `clsClaimDataCollection.GetWorkerClaimHist`/`GetClaimsForPolicy`/`GetActiveClaimsForWorker` with a worker ID or policy number |
| **Inputs** | Claim ID or claim number; for collection retrieval: worker ID, or policy number plus optional policy-period start/end dates, `ActiveOnly`, conflict/exposure handling flags |
| **Outputs** | Populated `clsClaimData` (single claim) or `clsClaimDataCollection` (claim history); active support-order count; MCO short description; total amount paid (lazy) |
| **Primary components** | `clsClaimData.GetData`, `clsClaimData.GetDataAsync`, `clsClaimData.AfterRetrieve`, `clsClaimDataCollection.BeforeRetrieve`/`AfterRetrieve`, `CCClaimDataApi.Claim.ClaimApiClient.GetClaimDataByClaimNumberAsync` |
| **Entry point** | `Business\SAIF.Business.View.Claim\clsClaimData.vb`, `Business\SAIF.Business.View.Claim\clsClaimDataCollection.vb` |

## Steps

1. **Single-claim retrieval by ID.** `clsClaimData.GetData(dataPortalInfo, claimID)` builds a `Criteria` and calls the framework's synchronous API retrieval, which sets `inAPIRequest.Route` to the claim-by-ID route and dispatches the request.
   - `BeforeRetrieve` only sets the route when `MyCriteria.ClaimID > 0`; a companion overload accepts a claim number string instead of an ID.
2. **Single-claim retrieval by ID, asynchronous.** `clsClaimData.GetDataAsync(dataPortalInfo, httpClient, claimID)` calls `ClaimApiClient.GetClaimDataByClaimNumberAsync` directly against route `v1/GeneralClaimData/Claim/{claimId}`, bypassing the synchronous framework request pipeline for callers that already hold an `HttpClient`.
   - On failure: if the JSON response cannot be deserialized into `InjuryClaim`, the client throws with a message that includes the claim ID and the raw response body.
3. **Populate the claim header.** `AfterRetrieve` reads a `ResponseData(Of InjuryClaim)` envelope from the API result.
   - If `StatusCode = HTTP 200`: the hundreds of `clsClaimData` properties are mapped from the `InjuryClaim` DTO (status, coverage, injury, jurisdiction, worker, policy, and related code fields), and `RetrieveActiveSupportOrderCount()` runs immediately (step 4).
   - If the status code is not 200: the claim object is not populated with claim data (behavior beyond the status check is not further branched in this method*).
4. **Count active support orders.** `RetrieveActiveSupportOrderCount()` issues an inline Oracle count query filtered to the claim's worker ID ([BR-002](../business-rules.md#br-002-active-support-orders-exclude-terminated-rows), [SQL-001](../sql/SQL-001.md), [cl_claim_support_order](../database-tables.md#cl-claim-support-order)) and stores the result in `ActiveSupportOrderCount`, which also backs `IsActiveSupportOrder`.
5. **Resolve MCO short description (lazy).** The first read of `McoShortDescr` triggers a lazy read that queries `MCO_PLAN` for the plan's short description ([SQL-002](../sql/SQL-002.md), [MCO_PLAN](../database-tables.md#mco-plan)).
   - If a current MCO tier is also known: the tier description is appended to the short description.
6. **Resolve total amount paid (lazy).** The first read of `TotalAmountPaid` dispatches the Oracle stored procedure `sp83411_Calc_Total_Paid` ([SQL-003](../sql/SQL-003.md)).
   - Oracle source for this procedure was not found during source review, so this call path may be dead or environment-specific code.**
7. **Worker claim history retrieval.** `clsClaimDataCollection.GetWorkerClaimHist`/`GetActiveClaimsForWorker` set the collection route to the worker-ID claim-history endpoint in `BeforeRetrieve`; worker-ID routing takes precedence over policy-based routing whenever a worker ID is supplied.
8. **Policy claim history retrieval.** `GetClaimsForPolicy` sets the collection route to a policy-number or policy-period endpoint.
   - If `StartDate = Date.MinValue`: the policy-number-only route is used instead of the policy-period route.
9. **Populate the claim collection.** `AfterRetrieve` reads `ResponseData(Of List(Of InjuryClaim))` and constructs one `clsClaimData` per returned claim, reusing the same population logic as single-claim retrieval (step 3), then applies conflict and exposure exclusion/masking per the caller's `ConflictHandling`/`ExposureHandling` settings.
   - `FilterActiveClaimStatus()` is available to narrow an already-loaded collection down to active-status claims only.
10. **Expose lazy sub-objects.** Once a `clsClaimData` is populated, related detail — `Reserves`/`AllReserves`, `AwardInfo`, `Beneficiaries`, `MedicalConditions`, `ClaimNotes`, `McoHistory`, `EAIPData`, `VocationalDetails`, `PaymentsData` — is lazily retrieved on first property access rather than eagerly loaded with the claim header. See the dedicated operation pages for each of these.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller requests claim data]) --> Which{Single claim or history search?}
	Which -->|Single claim, sync| SyncGet[GetData resolves route by ID]
	Which -->|Single claim, async| AsyncGet[GetDataAsync calls ClaimApiClient directly]
	Which -->|Worker or policy history| CollRoute[Collection resolves worker or policy route]
	SyncGet --> ApiCall[Claim data API call]
	AsyncGet --> ApiCall
	CollRoute --> ApiCall
	ApiCall --> Status{API status 200?}
	Status -->|No| Empty([Claim not populated])
	Status -->|Yes| Map[Map InjuryClaim fields onto clsClaimData]
	Map --> Supp[Count active support orders]
	Supp --> Done([Return populated claim or claim collection])
	Done --> Lazy[Lazy sub-object access:<br>reserves, award, beneficiaries,<br>notes, MCO history, EAIP, vocational]
```

## Failure and edge-case behavior

- Async deserialization failures throw immediately rather than returning a partially populated claim, so callers using `GetDataAsync` must handle exceptions explicitly.
- A non-200 API status leaves the claim object unpopulated with no explicit error surfaced to the caller from `AfterRetrieve` alone.*
- `sp83411_Calc_Total_Paid` (`TotalAmountPaid`) could not be located in the Oracle source reviewed, so this lazy read may fail or be effectively dead code in the current environment.**
- Worker-ID-based collection routing always takes precedence over policy-based routing when both are supplied, so callers relying on policy filtering must omit the worker ID.

## 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. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources

- `Business\SAIF.Business.View.Claim\clsClaimData.vb`
- `Business\SAIF.Business.View.Claim\clsClaimDataCollection.vb`
- `Business\SAIF.Business.View.Claim\ClaimData.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Claim\ClaimApiClient.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Claim\Dto\InjuryClaim.vb`
- `Business\SAIF.Business.View.Claim\clsMcoData.vb`