Skip to content
RightCapital Knowledge Base

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

Section titled “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
Developer Qianwei Hao
Cron Owner qianwei.hao
IntegrationType IntegrationType::FIDELITY
Default Account Type INVESTMENT

How It Works

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Reference Format in DB”

integrations.reference is stored as:

570:{client_id}

See TriggerSyncController.php:145 for the routing logic.

Reference → S3 Path Conversion

Section titled “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

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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

Section titled “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

Section titled “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

Section titled “Code Locations”

Backend Integration Package

Section titled “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)

Section titled “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

Section titled “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

Section titled “Common Issues”

Mismatched CH/CT Boundaries

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled ““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

Section titled “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

Section titled “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

Section titled “Contact Information”
Purpose Email
Technical support nftransmissioninstalls@fmr.com
Integration support integrationsupport@fmr.com
Transmission platform transmissionplatform@fmr.com
Business inquiries avdf@fmr.com
Section titled “Related”