Nationwide

Nationwide is a data sync integration that imports annuity accounts from Nationwide Financial.

Overview

Attribute	Value
Integration Type	Data Sync (Inbound)
Authentication	OAuth 2.0 (HTTP Basic for token exchange)
Data Flow	Nationwide → RightCapital
Entity Types	Accounts (Annuity) only
Owner	Winston Li

Data Imported

Annuity investment accounts mapped to ANNUITY_TAXABLE subtype.

Nationwide Type	RightCapital Annuity Type
Fixed	Fixed Annuity
Variable	Variable Annuity

Note: Holdings only fetched for Variable annuities. Fixed annuities have no subaccount allocations.

API Endpoints

Endpoint	Method	Purpose
.../contracts	GET	List contracts
.../contracts/{id}/investments	GET	Get holdings

Key Features

• Variable annuities only get holdings
• User ID from JWT - Extracted from id_token claim
• 30-day refresh token - Advisor must re-authenticate after expiration
• Message ID header - Each request includes unique X-NW-Message-ID UUID

Code Locations

Component	Path
Connector	retail-api/app/Integrations/Nationwide/Connector.php
Integrator	retail-api/app/Integrations/Nationwide/Integrator.php
Models	retail-api/app/Integrations/Nationwide/Models/

Common Issues

Refresh Token Expired

Symptom: UnauthorizedException during sync

Solution: Advisor must re-authenticate (30-day limit)

Related

• Allianz API - Similar annuity integration