Fidelity

Fidelity is a self-hosted file-based integration that imports investment accounts and holdings from Fidelity’s custodian platform into RightCapital. Fidelity pushes daily fixed-width text files (compressed as .DAT.ZIP) to RightCapital’s SFTP server.

Overview

Attribute	Value
Integration Type	File-based (Self-hosted)
File Format	Fixed-width text (NAM, POS, TAX), delivered as .DAT.ZIP
Data Flow	Fidelity SFTP Push → RightCapital
Data Sync	Daily batch sync
Owner	Qianwei Hao
IntegrationType	IntegrationType::FIDELITY
Default Account Type	INVESTMENT

How It Works

Fidelity FTP Server
    ↓ (SFTP Push, *.DAT.ZIP)
ftp.rightcapital.com (vendor inbound)
    ↓
Collector (Download → Process → Upload to S3)
    ↓
Finalizer (group by ria_id / rep_code)
    ↓
Retail-API Sync (Reader → Extractor → Mapper → DB)

File Types

Fidelity sends configurable file streams (typically 3 core, plus optional ones):

FileType Enum	Filename Pattern	Purpose	Frequency
NAM	*NABASE*	Account names, types, owner first/last name	Daily
POS	*POSITD*	Positions: CUSIP, quantity, price, market value	Daily
TAX	*_TLAOPENDELTA_*	Cost basis delta (aggregated per CUSIP)	Daily
(n/a)	*_ACCTBALD_*	Account balance summary	Daily (not actively used by Reader)
(n/a)	*_TLAOPENFULL_*	Full tax lots (complete snapshot)	Weekly (not actively used by Reader)

File naming pattern: ###_*_FILENAME_DATE.DAT, where ### = firm ID (570), DATE = CCYYMMDD.

Line Record Prefixes

Each file uses single-character prefixes to mark line types:

Prefix	Meaning
H	File header (e.g., transmission date for POS at offset 62, format MMDDYYYY)
D	Detail data row
CH	Client header — contains client_id at offset 3 (length 20)
CT	Client tailer — must match the preceding CH client_id

The Reader streams header (H) lines and only D lines belonging to the target client (matched between CH/CT boundaries).

Key Identifiers

Identifier	Description	Source
IBD Code	570 (Fidelity’s broker code)	Hard-coded prefix
client_id	Fidelity client identifier inside file	Read from CH line
account_reference	BRANCH(3) + ACCOUNT_NUMBER(6) (e.g., X46629715)	NAM file, offset 8, length 9

Reference Format in DB

integrations.reference is stored as:

570:{client_id}

See TriggerSyncController.php:145 for the routing logic.

Reference → S3 Path Conversion

The 570:{client_id} reference is converted to 570/{client_id} for S3 directory lookup:

// IntegrationType.php:306
FIDELITY => Str::replace(':', '/', $integration_reference)

See IntegrationType.php:306.

Admin Validation

The admin-api validates Fidelity reference format with regex /^\w+:\w+$/:

See ValidateFidelityReference.php.

If the format is invalid, the error message is: “Firm ID and Client ID are required.”

Advisor Setup Flow (Frontend)

The frontend fidelity.component.tsx presents this step-by-step process to advisors:

1. Email Fidelity technical support — request Fidelity Integration Xchange enrollment
2. Register — complete the Integration Xchange registration process
3. Submit client header — provide the client_id that identifies their accounts in the files
4. Wait 3-5 business days — for setup to take effect

Field Extraction (NAM)

Record #	Offset	Length	Field
101	40	10	Short name (first byte & → account closed)
101	71	2	Account type code
102 (B at offset 190)	192	50	Business / trust name
102 (else)	192	12	First name
102 (else)	214	25	Last name

Closed account filter: any account whose short name starts with & is excluded from sync.

Account number masking: stored as BRANCH(3) + XXX + LAST(3), e.g., X46XXX715.

Field Extraction (POS)

Offset	Length	Field
6	9	account_reference
18	9	CUSIP
28	2	Security type + modifier
49	9	Symbol
58	9.9 (signed)	Market price
104	13.5 (signed)	Settlement-date quantity
334–453	6 × 20	Security description lines 1–6 (concatenated)
568	15.2 (signed)	Position market value
868	15	ISIN

Numeric fields use trailing-sign convention: integer + fraction + +/- sign character.

Field Extraction (TAX)

Offset	Length	Field
2	9	account_reference
12	9	CUSIP
209	15.2 (signed)	Cost basis amount (summed per CUSIP)

Account Type Mapping

Fidelity Code	RC Account Subtype
00	taxable
01	taxable
02	taxable
03	taxable
04	taxable
05	taxable
06	taxable
07	traditional_ira
08	roth_ira
09	sep_ira
10	simple_ira
11	taxable
12	rollover_ira
13	inherited_ira
14	inherited_roth_ira
15	designated_roth_401k
16	401k
17	trust
18	403b
19	profit_sharing
20	money_purchase
21	401k
22	401k
23	defined_benefit
24	employee_stock_ownership
25	457
26	non_qualified_deferred_comp
27	trust
28	custodian
29	trust
30	529
31	taxable
32	taxable
33	traditional_ira
34	sep_ira
35	simple_ira
36	401k
37	trust
38	roth_ira
39	inherited_ira
40	inherited_roth_ira
41–80	taxable (various trust/corp subtypes)

Security Type Mapping

Vendor Code	Security Type
00	equity
01	equity
10	fixed_income
20	fund
21	fund
50	fund
51	fund
52	fund
60	fund
61	fund
70	fund
71	fund
72	fund
90	cd
93	fund
94	fund
9T	fixed_income
C0	fixed_income
FF	fund
FR	fund
FS	fund
FT	fund

Code Locations

Backend Integration Package

backend/packages/libs/integrations-file-based/src/Fidelity/

Component	File
Integrator	Integrator.php
Reader	Reader.php (CH/CT client filtering)
Extractor	Extractor.php (offset-based field extraction)
Config	Config.php (default INVESTMENT account type)
Sync	Sync.php
FileType enum	FileType.php (NAM/POS/TAX)
Models	Models/InvestmentAccount.php, Models/Holding.php

Collector (file pickup pipeline)

integrations/collector/app/

Component	File
Vendor	Vendors/FidelityVendor.php (orchestrates collect/finalize/run)
Downloader	Downloaders/FidelityDownloader.php (filters *.DAT.ZIP)
Processor	Processors/FidelityProcessor.php
Uploader	Uploaders/FidelityUploader.php
Finalizer	Finalizers/FidelityFinalizer.php

Console Commands

Command	Location
php artisan fidelity:collect [--as_of=]	collector/app/Console/Commands/Fidelity/Collect.php
php artisan fidelity:finalize	collector/app/Console/Commands/Fidelity/Finalize.php
php artisan fidelity:run	collector/app/Console/Commands/Fidelity/Run.php
php artisan integrations:fidelity:sync	retail-api/app/Console/Commands/Integrations/Fidelity/Sync.php

Common Issues

Mismatched CH/CT Boundaries

The Reader throws if a CH client header is encountered before its matching CT tailer, or if the file ends with an unclosed header. This usually indicates a truncated upload — re-pull from the source.

POS Header Missing Transmission Date

The first H line in a POS file is required (offset 62, format MMDDYYYY). If a D row appears before any H, extraction throws “POS file has wrong format”.

Note: Fidelity’s documentation incorrectly states the date format is MMDDYY. Actual format is MMDDYYYY.

Closed Accounts

Accounts where the NAM short name starts with & are filtered out. If an advisor expects an account but it’s missing, check the raw NAM file for the & prefix.

CUSIP Aggregation

Both POS and TAX may have multiple rows per (account_reference, CUSIP). The Extractor sums quantity, market value (POS), and cost basis (TAX). If totals look off, inspect the raw file for duplicate CUSIPs.

”T” Line Trailer Confusion

If a NAM data value starts with “T” (e.g. a first/last name like “TAYLOR”), the parser mistakes it for the Trailer record and stops mid-file, blocking all subsequent advisor sections. This is a Fidelity producer-side formatting bug. The corrective action is requesting Fidelity reissue the file with “T” only in the final trailer at EOF.

Large Files

NABASE files can reach 4 GB+ decompressed. Always use funzip for streaming (sandbox /tmp is only ~10 GB). Never decompress fully to disk.

Missing Account Troubleshooting

When an advisor reports a missing account:

1. rg (global search) the raw file for the account number
2. Find the nearest ^CH line above it — that determines which client_id header it belongs to
3. If under a subscribed header but not parsed → RC bug (escalate to engineering)
4. If under an unsubscribed/wrong advisor header → vendor header misassignment (Fidelity assigned the wrong client_id)
5. If not found in any header → vendor data missing (Fidelity didn’t include it)

Contact Information

Purpose	Email
Technical support	nftransmissioninstalls@fmr.com
Integration support	integrationsupport@fmr.com
Transmission platform	transmissionplatform@fmr.com
Business inquiries	avdf@fmr.com

Related

• File-based Integration Patterns
• File-based Vendor Specifics
• Pershing — Similar self-hosted fixed-width custodian integration
• Vendor Management — Cross-vendor operations reference