Safeco Auto is the quote-to-bind flow for Safeco Auto insurance. Customers arrive from DA (Dealer Application) via a deep link and complete a multi-step flow: confirm drivers and vehicles, select coverages, apply discounts, and bind with payment via Hydra.
Integration
| Aspect | Technology |
|---|
| Protocol | ACORD XML (JSON-represented, converted by SafecoV3XmlConverterService) |
| Transaction types | RC1 (initial), RC1+CC (CLUE), RC1+ADD (driver discovery), RC2 (final rate), RC3 (bind) |
| Payment | Hydra iframe (Liberty Mutual) for credit card / ACH |
| Bind status | Server-Sent Events (SSE) for real-time status |
| Auth | Switchboard OAuth (bearer token) for Safeco API; Hydra OAuth for payment |
| Session | CarrierQuoteSession in Prisma + Redis session store |
Architecture
NestJS Module
SafecoCarrierModule (libs/apis/carriers/safeco/src/lib/safeco-carrier.module.ts) exports:
| Provider | Token | Purpose |
|---|
SafecoV3RateService | — | RC1/RC2 rate flows |
SafecoV3BindService | — | RC3 bind |
SafecoV3ReportsService | — | CC/ADD/MVR reports |
SafecoV3FieldMapperService | — | Session → ACORD XML mapping |
SafecoV3ApiClient | SAFECO_API_CLIENT (via proxy) | HTTP client to Safeco |
SafecoV3AuthService | — | Switchboard OAuth tokens |
SafecoHydraService | — | Hydra iframe URL + validation |
HydraOAuthTokenManagerService | — | Hydra OAuth tokens |
SafecoCdmAdapter | — | CDM integration |
The API client uses a proxy pattern — SafecoV3ApiClientProxy wraps the real client and mock client, allowing test/dev switching.
API Endpoints
All under POST /api/v1/ghcms/safeco/ unless noted:
| Endpoint | Method | Purpose |
|---|
/initial-quote | POST | Load existing CRN quote (no Safeco API call) |
/update-quote | POST | Update pricing — plain RC1 |
/rate-with-reports | POST | Full 4-step rate flow (RC1+CC, RC1+ADD, RC2) |
/rate | POST | Direct RC2 rate call |
/payment-plans | POST | RC3 payment plan retrieval |
/hydra-url | POST | Generate Hydra iframe URL |
/hydra-validate | POST | Validate Hydra payment instrument |
/bind | POST | Async bind — returns 202, streams status via SSE |
/bind/status/stream | GET (SSE) | Real-time bind status stream |
/documents/:sessionId | GET | List policy documents |
/documents/:sessionId/download/:documentType | GET | Download a policy document |
Domain Types
| Type | Location | Purpose |
|---|
QuoteStatus | domain/entities/quote.entity.ts | DRAFT, RATED, SELECTED, EXPIRED |
PolicyStatus | domain/entities/policy.entity.ts | PENDING, BOUND, ACTIVE, CANCELLED |
SafecoDriverDto | v3/application/dtos/ | Driver data for rate requests |
SafecoVehicleDto | v3/application/dtos/ | Vehicle data for rate requests |
SafecoCoverageDto | v3/application/dtos/ | Coverage data |
SafecoPaymentPlanDto | v3/application/dtos/ | Payment plan details |
BindSessionData | v3/application/services/ | Composite session for bind |
HydraPaymentInstrument | v3/application/services/ | Tokenized payment |
SafecoAutoQuoteData | v3/infrastructure/xml/ | ACORD XML JSON representation |
Key Files
| Area | Location |
|---|
| Portal flow | apps/fastlane-portal/src/app/pages/carriers/safeco/auto/ |
| Flow config | apps/fastlane-portal/src/app/pages/carriers/safeco/auto/flow-config.ts |
| API Gateway controller | apps/apis/fastlane-api-gateway/src/app/controllers/safeco.controller.ts |
| Gateway handlers | apps/apis/fastlane-api-gateway/src/app/handlers/safeco-*.handler.ts |
| Safeco lib | libs/apis/carriers/safeco/ |
| Rate service | libs/apis/carriers/safeco/src/v3/application/services/safeco-v3-rate.service.ts |
| Bind service | libs/apis/carriers/safeco/src/v3/application/services/safeco-v3-bind.service.ts |
| Field mapper | libs/apis/carriers/safeco/src/v3/infrastructure/mapping/safeco-v3-field-mapper.service.ts |
| ACORD XML utils | libs/apis/carriers/safeco/src/v3/infrastructure/xml/ |
| Hydra service | libs/apis/carriers/safeco/src/v3_1/application/services/safeco-hydra.service.ts |
| Constants | libs/apis/carriers/safeco/src/v3/constants/safeco.constants.ts |
Documentation
- Entry from DA — Deep link, session init, routing
- Quote Flow — Steps, API calls, rate flow, session management
- Bind Flow — Hydra, bind API, retry logic, response parsing
- SSE Bind Status — Real-time bind status stream
- ACORD XML Protocol — Transaction types, envelope structure, entity refs
- Hydra Payment — Iframe integration, OAuth, validation
- Coverage Rules — Plan tiers, validation, derivations
- Knockouts & Eligibility — Client-side and server-side eligibility checks
Environment Variables
| Variable | Purpose |
|---|
SAFECO_RC1_RC2_URL | Safeco ACORD API endpoint (RC1/RC2) |
SAFECO_RC3_URL | Safeco ACORD API endpoint (bind) |
SAFECO_RC1_RC2_ATTRIBUTION_ID | Partner attribution header |
SAFECO_API_TIMEOUT | API timeout (default 30s) |
SAFECO_HYDRA_BASE_URL | Hydra payment API |
SAFECO_HYDRA_CLIENT_ID | Hydra OAuth client ID |
SAFECO_HYDRA_CLIENT_PROFILE_ID | Hydra client profile |
SAFECO_HYDRA_CALLBACK_URL | Hydra iframe callback |
SAFECO_HYDRA_CSS_URL | Hydra iframe custom CSS |