---
title: Retrieve an agency by sequence number
summary: Load one agency business object from the AGENCY table.
status: draft
owner: Technical Writer
last_reviewed: 2026-07-31
library: SAIF.Business.Policy.Agency
reference_type: package
operation_id: OP-001
trigger: A caller requests one agency by sequence number.
---

# Retrieve an agency by sequence number

This operation executes the BOF retrieve lifecycle for `clsAgency`, loads one `AGENCY` row by `AgencySeqNum`, and returns a populated agency object or a default object when no row is found.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-001 |
| **Trigger** | A caller invokes `clsAgency.GetAgency(inDataportal, inAgencySeqNum)`. |
| **Inputs** | `IDataPortalInfo`, `AgencySeqNum` |
| **Outputs** | `clsAgency` |
| **Primary components** | `clsAgency.GetAgency`, `clsAgency.Criteria`, `clsAgency.BeforeRetrieve`, `clsAgency.AfterRetrieve` |
| **Entry point** | `Business\SAIF.Business.Policy.Agency\clsAgency.vb` |

## Steps
1. Build a `clsAgency.Criteria` instance with the portal context and requested agency sequence number ([BR-002](../business-rules.md#br-002-agency-sequence-number-is-required), [BR-025](../business-rules.md#br-025-identity-keys-are-agency-seq-contract-seq-and-agent-number)).
2. Pass the criteria to the BOF data portal so the retrieve lifecycle can execute on behalf of the agency object ([BR-024](../business-rules.md#br-024-the-library-is-retrieve-only)).
3. In `BeforeRetrieve`, assign [SQL-001](../sql/SQL-001-retrieve-agency-by-sequence-number.md) and bind `:AgencySeqNum` against [AGENCY](../database-tables.md#agency).
4. Execute the query and return a reader positioned for one agency row.
5. In `AfterRetrieve`, call `Fill` only when a row exists; otherwise leave the object at its default state ([BR-001](../business-rules.md#br-001-missing-key-retrieval-returns-a-default-object)).
6. Mark the object old and expose its status, paperless, and naming helpers for later callers ([BR-018](../business-rules.md#br-018-yn-flags-convert-through-framework-boolean-helpers), [BR-019](../business-rules.md#br-019-special-agency-sequence-numbers-identify-saif-and-not-yet-appointed-agencies), [BR-020](../business-rules.md#br-020-agency-and-producer-display-names-are-title-cased-and-abbreviated-consistently)).

## Process flow

The following diagram visualizes the retrieve flow for one agency.

```mermaid
flowchart TD
  Start([GetAgency]) --> Criteria[Build criteria]
  Criteria --> SQL[Assign SQL-001]
  SQL --> Query[Query AGENCY]
  Query --> Found{Row found?}
  Found -->|Yes| Fill[Fill clsAgency]
  Found -->|No| Default[Return default object]
  Fill --> End([Agency returned])
  Default --> End
```

## Failure and edge-case behavior
- Missing rows return a default-initialized agency object instead of throwing a not-found exception.
- Any caller that attempts to use persistence-oriented BOF SQL properties on the criteria hits the retrieve-only guard.

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

## Sources
- `Business\SAIF.Business.Policy.Agency\clsAgency.vb`