---
title: Claim contacts and beneficiaries retrieval
summary: Retrieves claim contact roles and beneficiary/person records for a claim from the claim contacts API.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.View.Claim
reference_type: package
operation_id: OP-VC-05
trigger: Caller reads `clsClaimData.Beneficiaries`, or calls `clsClaimPersonViewCollection`/`ClaimContactsCollection` retrieval directly
---

# Claim contacts and beneficiaries retrieval

This operation retrieves the set of people associated with a claim — role-based contacts (adjuster, supervisor, EAIP specialist, RTW consultant, safety consultant, vocational coordinator, attending physicians, worker representatives, beneficiaries) — from the claim contacts API, and maps beneficiary-type contacts into `clsClaimPersonView` objects for claim-view consumers.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-VC-05 |
| **Trigger** | Caller reads `clsClaimData.Beneficiaries` (which calls `RetrieveBeneficiaries()`), or directly calls `clsClaimPersonViewCollection.GetClaimPersons`/`GetBeneficiaries`, or `ClaimContactsCollection.GetData` |
| **Inputs** | Claim number (for `ClaimContactsCollection`); claim ID plus a `ContactTypes` value (for `clsClaimPersonViewCollection`); optionally a pre-fetched `ClaimContacts` payload |
| **Outputs** | `ClaimContacts` (grouped role contacts) or `clsClaimPersonViewCollection` of `clsClaimPersonView` (currently beneficiaries only) |
| **Primary components** | `ClaimContactsCollection.GetData`, `clsClaimPersonViewCollection.BeforeRetrieve`/`AfterRetrieve`, `clsClaimPersonView.Load` |
| **Entry point** | `Business\SAIF.Business.View.Claim\CCClaimDataApi\Contact\ClaimContactsCollection.vb`, `Business\SAIF.Business.View.Claim\clsClaimPersonViewCollection.vb`, `Business\SAIF.Business.View.Claim\clsClaimPersonView.vb` |

## Steps

1. **Retrieve raw claim contacts.** `ClaimContactsCollection.GetData(dataPortalInfo, claimNumber)` builds a request against route `v1/{controller}/Claim/Contacts/ClaimNumber/{claimNumber}` (client key `CCClaimDataApi`, controller `GeneralClaimData`) and returns the `.ClaimContacts` payload from the first result.
2. **Select the contact-type route.** `clsClaimPersonViewCollection.BeforeRetrieve` currently only implements retrieval for `ContactTypes.BENEFICIARY`.
   - If a different contact type is requested and no `ClaimContacts` was pre-supplied: `BeforeRetrieve` throws `"The operation is not implemented"`.
3. **Fetch or reuse contacts.** If the criteria's `ClaimContacts` is not already populated, the collection calls the claim contacts API for the claim; if it was pre-supplied by the caller, that payload is reused instead of issuing another API call.
4. **Map contacts to person views.** `AfterRetrieve` reads `ResponseData(Of ClaimContacts)` and maps each relevant `Contact` row (e.g. each `Beneficiary.Beneficiary` entry) into a `clsClaimPersonView` via `Load(contact, contactType)`.
5. **Resolve the person identifier.** `clsClaimPersonView.Load` resolves `PersonID` from the contact's provider location sequence number when nonzero, otherwise from a numeric `PublicID` ([BR-007](../business-rules.md#br-007-claim-person-identifier-resolution-requires-a-provider-location-number-or-a-numeric-public-id)).
   - On failure: if neither identifier is usable, `Load` throws `"Unexpected public ID..."`.
6. **Map relationship and demographic fields.** `Load` derives `Relationship` from `RelationshipToWorkerCode` via a case mapping, maps `Type` from `ContactTypes`, and extracts a birth-certificate-received date from the contact's certificate list when present.
7. **Return the collection.** The populated `clsClaimPersonViewCollection` is returned to the caller (e.g. exposed as `clsClaimData.Beneficiaries`).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller requests contacts or beneficiaries]) --> Which{Raw contacts or<br>person-view collection?}
	Which -->|Raw contacts| CallContacts[ClaimContactsCollection.GetData]
	CallContacts --> ReturnContacts([Return ClaimContacts])
	Which -->|Person views| Type{Contact type is BENEFICIARY?}
	Type -->|No, and no contacts supplied| NotImpl([Throw: operation not implemented])
	Type -->|Yes, or contacts supplied| HaveContacts{ClaimContacts already supplied?}
	HaveContacts -->|No| FetchApi[Call claim contacts API]
	HaveContacts -->|Yes| UseSupplied[Reuse supplied ClaimContacts]
	FetchApi --> MapPersons[Map each Contact to clsClaimPersonView]
	UseSupplied --> MapPersons
	MapPersons --> ResolveId{PersonID resolvable?}
	ResolveId -->|No| IdError([Throw: unexpected public ID])
	ResolveId -->|Yes| Done([Return clsClaimPersonViewCollection])
```

## Failure and edge-case behavior

- Requesting any contact type other than `BENEFICIARY` without pre-supplying `ClaimContacts` throws `"The operation is not implemented"`, so callers needing other role contacts must use `ClaimContactsCollection.GetData` directly instead.
- A contact row lacking both a provider location sequence number and a numeric public ID causes the entire retrieval to fail with an unhandled identifier error, rather than skipping the unusable row.
- `GetContacts(...)` returns an empty list for a `Nothing` input rather than throwing, so a missing contact group (e.g. no beneficiaries on the claim) resolves to zero rows.*

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.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.View.Claim\CCClaimDataApi\Contact\ClaimContactsCollection.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Contact\Dto\ClaimContacts.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Contact\Dto\Contact.vb`
- `Business\SAIF.Business.View.Claim\clsClaimPersonView.vb`
- `Business\SAIF.Business.View.Claim\clsClaimPersonViewCollection.vb`
- `Business\SAIF.Business.View.Claim\clsClaimData.vb`