---
title: Guardian and power-of-attorney management
summary: Retrieves guardian and power-of-attorney contact snapshots from claim-contact APIs and hydrates their nested address objects.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business.Claim.Person
reference_type: package
operation_id: OP-PER-07
trigger: Caller requests guardians by claim ID, an injured-worker guardian by claim number, or a power-of-attorney contact by claim number.
---

# Guardian and power-of-attorney management

Guardian and power-of-attorney management is implemented as API-backed contact hydration rather than BOF CRUD persistence. The library exposes one claim-level guardian list built from beneficiary guardians, one injured-worker guardian lookup by claim number, and one injured-worker power-of-attorney lookup by claim number. Each flow maps the returned contact into a domain object and loads a nested address object from the contact's address payload.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PER-07 |
| **Trigger** | Caller requests guardian or power-of-attorney contact data for a claim ID or claim number |
| **Inputs** | `ClaimID` or claim number; `CCClaimDataApi` claim-contact payloads; guardian or power-of-attorney contact fields and nested address data |
| **Outputs** | `List(Of clsGuardian)` from `clsGuardianCollection`; a single injured-worker `clsGuardian`; a single `clsPowerOfAttorney`; hydrated `clsGuardianAddress` or `clsPowerOfAttorneyAddress` children |
| **Primary components** | `clsGuardianCollection.Guardians`, `clsGuardian.GetInjuredWorkerGuardian`, `clsGuardian.Load`, `clsPowerOfAttorney.GetPowerOfAttorneyByClaimNumber`, `clsPowerOfAttorneyAddress.LoadPowerOfAttorneyAddress` |
| **Entry point** | `Business\SAIF.Business.Claim.Person\clsGuardianCollection.vb` |

## Steps

1. **Retrieve claim-level guardian contacts by claim ID.** `clsGuardianCollection` builds the `v1/GeneralClaimData/ClaimsContacts/{ClaimID}` route, requests claim contacts, filters the beneficiary list to contacts whose `Guardian` is not `Nothing`, applies `Distinct()`, loads each guardian into `clsGuardian`, and returns the resulting list.
2. **Hydrate each guardian snapshot.** `clsGuardian.Fill` copies certificate dates, demographic fields, phone flags and numbers, name parts, tax ID, worker and person IDs, and update metadata from the contact, then loads `guardian.PrimaryAddress` into a child `clsGuardianAddress`.
3. **Retrieve the injured worker's guardian by claim number.** `clsGuardian.GetInjuredWorkerGuardian` calls `v1/GeneralClaimData/ClaimsContacts/ClaimNumber/{ClaimNumber}` and, when `InjuredWorker.Guardian` is present, loads that contact into a new `clsGuardian` before returning it.
4. **Retrieve the injured worker's power of attorney by claim number.** `clsPowerOfAttorney.GetPowerOfAttorneyByClaimNumber` calls the same claim-number route and, when the injured worker guardian is present, fills a `clsPowerOfAttorney` from `InjuredWorker.PowerOfAttorney`.
5. **Hydrate the power-of-attorney address child.** `clsPowerOfAttorney.Fill` chooses `PrimaryAddress` when present or falls back to `MailingAddress`, loads that address into `clsPowerOfAttorneyAddress`, and registers the address as a child object on the power-of-attorney instance.
6. **Expose the loaded objects as read-oriented snapshots.** The public entry points on these classes only retrieve and hydrate contact data; this source set does not implement a local guardian or power-of-attorney save workflow.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Request guardian or power-of-attorney data]) --> Which{Lookup type?}
    Which -->|Claim ID| GList[Load claim contacts and filter beneficiary guardians]
    Which -->|Claim number guardian| GSingle[Load injured worker guardian]
    Which -->|Claim number power of attorney| PSingle[Load injured worker power of attorney]
    GList --> GAddr[Load guardian primary address]
    GSingle --> GAddr
    PSingle --> PAddr[Load primary or mailing address]
    GAddr --> Done([Return hydrated guardian data])
    PAddr --> Done2([Return hydrated power-of-attorney data])
```

## Failure and edge-case behavior

- `clsGuardianCollection` only returns guardians attached to beneficiary contacts; other contact roles in the claim-contact payload are ignored by this flow.
- `GetInjuredWorkerGuardian` returns an empty `clsGuardian` object when the API response does not contain `InjuredWorker.Guardian`.
- `GetPowerOfAttorneyByClaimNumber` checks `InjuredWorker.Guardian IsNot Nothing` before reading `InjuredWorker.PowerOfAttorney`, so power-of-attorney data is skipped whenever the guardian object is absent.
- `clsPowerOfAttorney.IsDirty` is hardcoded to `False` and `clsPowerOfAttorney.IsValid` is hardcoded to `True`, so local edits are not surfaced as pending or invalid changes by this class.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

## Sources
- `Business\SAIF.Business.Claim.Person\clsGuardian.vb`
- `Business\SAIF.Business.Claim.Person\clsGuardianAddress.vb`
- `Business\SAIF.Business.Claim.Person\clsGuardianCollection.vb`
- `Business\SAIF.Business.Claim.Person\clsPowerOfAttorney.vb`
- `Business\SAIF.Business.Claim.Person\clsPowerOfAttorneyAddress.vb`