Skip to content

SAIF.Agency.Api overview

SAIF.Agency.Api publishes the agency distribution channel — agencies, the agents who work at them, and the appointments that authorise those agents to write business — to the applications that need it. It owns the AGENCY schema and is the only service that writes agency contact details, so a change made through this API is immediately visible to every consumer rather than being replicated into local copies.

Purpose

  • Resolves an agency, its producer codes, and its servicing agents for applications that must attribute a claim, policy, or notice to a distribution partner.
  • Maintains agency contact details — mailing address, contact email, and contact phone — as the single authoritative copy used for correspondence.
  • Removes direct AGENCY schema access from consuming applications, so agency eligibility and status rules are enforced in one place.

Business context

Every policy SAIF writes is placed through an appointed agency, and almost every downstream process needs to know which one. Claims intake stamps the servicing agency on a new claim so that correspondence and commission reporting are correct; renewal notice generation resolves the servicing agent so the notice carries a named contact; the agency portal reads and maintains the agency's own contact details. If the service is unavailable, claims can still be entered but without agency attribution, and the nightly renewal notice run fails to resolve servicing agents and rejects the affected notices rather than mailing them to an unknown recipient.

Attribute Value
Business domain Agency distribution and appointment management
Owning team Agency Systems Team (ConfigureOpenTelemetry(o => o.Owner = "Agency Systems Team") in Global.asax.cs)
Data ownership Oracle AGENCY schema — AGENCY, AGENCY_CONTACT, AGENCY_CONTACT_AUDIT, AGENT, AGENCY_APPOINTMENT
Criticality Tier 2 (azure-pipelines.yml deployment stage tag criticality: tier-2)

Consumers

Consumer Type Endpoints used Authentication Notes
Agency portal Web application GET /v1/agencies/{agencyNumber}, GET /v1/agencies/{agencyNumber}/agents, PUT /v1/agencies/{agencyNumber}/contact Windows integrated, caller in AgencyRead and AgencyContactWrite The only consumer that writes. Agency staff maintain their own contact details through the portal.
SAIF.Claims.Intake Web application GET /v1/agencies, GET /v1/agencies/{agencyNumber} Windows integrated, application pool identity in AgencyRead Resolves the servicing agency from the producer code entered on the claim.
SAIF.Policy.RenewalNotice Batch job GET /v1/agencies/{agencyNumber}, GET /v1/agencies/{agencyNumber}/agents Windows integrated, scheduled task identity in AgencyRead Calls through the SAIF.Agency.Api.Client package to name the servicing agent on each renewal notice.

Both .NET consumers reference the generated SAIF.Agency.Api.Client package rather than constructing requests by hand; the agency portal calls the service directly from server-side controllers.

Base address

Environment Base address Resolved from
DEV https://agencyapi-dev.example.saif/agency Environment API config key AgencyApi.BaseUrl
TEST https://agencyapi-test.example.saif/agency Environment API config key AgencyApi.BaseUrl
PROD https://agencyapi.example.saif/agency Environment API config key AgencyApi.BaseUrl

Capability summary

Capability Owning component Endpoints Description
Agency lookup AgenciesController GET /v1/agencies/{agencyNumber} Returns a single agency with its status, producer codes, and current contact details
Agency search AgenciesController GET /v1/agencies Returns agencies matching a producer code, optionally including terminated agencies
Agency roster AgenciesController GET /v1/agencies/{agencyNumber}/agents Returns the agents currently appointed at an agency
Contact maintenance AgenciesController PUT /v1/agencies/{agencyNumber}/contact Replaces an agency's contact block and records the change for audit
Agent lookup and search AgentsController GET /v1/agents/{agentNumber}, GET /v1/agents Returns an individual agent or agents licensed in a given state
Appointment management AppointmentsController GET /v1/appointments/{appointmentId}, POST /v1/appointments Reads and creates the appointment records that link an agent to an agency

Request and response format

Aspect Finding
Media types JSON only — config.Formatters.XmlFormatter removed in WebApiConfig.Register
Serializer settings camelCase property names (CamelCasePropertyNamesContractResolver), ISO-8601 dates with DateTimeZoneHandling.Utc, NullValueHandling.Ignore
Response envelope DTOs returned directly; collection endpoints return a bare JSON array, not a wrapper object

Non-documented artifacts

  • Stock Web API 2 project scaffolding — Areas/HelpPage/, Views/Shared/Error.cshtml, and Content/Site.css — is unmodified template output and is excluded from this document set.

Sources

  • src/SAIF.Agency.Api/Global.asax.cs
  • src/SAIF.Agency.Api/App_Start/WebApiConfig.cs
  • src/SAIF.Agency.Api/Controllers/v1/AgenciesController.cs
  • src/SAIF.Agency.Api/Controllers/v1/AgentsController.cs
  • src/SAIF.Agency.Api/Controllers/v1/AppointmentsController.cs
  • src/SAIF.Agency.Api/Web.config
  • azure-pipelines.yml