The TIAA Financial Data Exchange (FDX) API provides customer account details to authorized fintechs and financial aggregators with customer consent. Built on the FDX open-standard (OAuth 2.0), it offers a secure alternative to screen scraping and enables third-party apps to retrieve account balances, transactions, investment positions, and income data from TIAA retirement and brokerage accounts.
openapi: 3.0.3
info:
title: TIAA Financial Data Exchange API
description: >-
The TIAA Financial Data Exchange (FDX) API provides authorized fintechs and
financial aggregators with secure access to customer account data, including
balances, transactions, investment positions, and income information from
TIAA retirement and brokerage accounts. This API is built on the FDX open
standard (v6.x) and uses OAuth 2.0 for customer-consented data sharing.
version: '6.0'
contact:
name: TIAA Developer Support
url: https://developer.tiaa.org/public/fdx
termsOfService: https://developer.tiaa.org/public/terms
license:
name: TIAA API License
url: https://developer.tiaa.org/public/terms
servers:
- url: https://api.tiaa.org/fdx/v6
description: TIAA FDX Production API
tags:
- name: Accounts
description: Customer account information and balances
- name: Transactions
description: Account transaction history
- name: Investments
description: Investment positions and holdings
- name: Customer
description: Customer profile and identity
- name: Tax
description: Tax document and income data
paths:
/accounts:
get:
operationId: listAccounts
summary: List Customer Accounts
description: Returns all accounts to which the customer has granted consent.
tags:
- Accounts
security:
- OAuth2: []
parameters:
- name: offset
in: query
schema:
type: integer
description: Pagination offset
required: false
- name: limit
in: query
schema:
type: integer
description: Maximum number of accounts to return
required: false
responses:
'200':
description: A list of accounts
content:
application/json:
schema:
$ref: '#/components/schemas/AccountList'
'401':
description: Unauthorized
'403':
description: Forbidden
/accounts/{accountId}:
get:
operationId: getAccount
summary: Get Account Details
description: Returns details for a specific account by account ID.
tags:
- Accounts
security:
- OAuth2: []
parameters:
- name: accountId
in: path
required: true
schema:
type: string
description: Unique account identifier
responses:
'200':
description: Account details
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'404':
description: Account not found
/accounts/{accountId}/transactions:
get:
operationId: listTransactions
summary: List Account Transactions
description: Returns transaction history for a specific account within an optional date range.
tags:
- Transactions
security:
- OAuth2: []
parameters:
- name: accountId
in: path
required: true
schema:
type: string
- name: startTime
in: query
schema:
type: string
format: date-time
description: Start of transaction date range (ISO 8601)
- name: endTime
in: query
schema:
type: string
format: date-time
description: End of transaction date range (ISO 8601)
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Transaction list
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'404':
description: Account not found
/accounts/{accountId}/positions:
get:
operationId: listPositions
summary: List Investment Positions
description: Returns current investment positions (holdings) for a specific account.
tags:
- Investments
security:
- OAuth2: []
parameters:
- name: accountId
in: path
required: true
schema:
type: string
responses:
'200':
description: Investment positions
content:
application/json:
schema:
$ref: '#/components/schemas/PositionList'
/customer:
get:
operationId: getCustomer
summary: Get Customer Profile
description: Returns the authenticated customer's profile information.
tags:
- Customer
security:
- OAuth2: []
responses:
'200':
description: Customer profile
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/tax-forms:
get:
operationId: listTaxForms
summary: List Tax Forms
description: Returns available tax documents (1099-R, 5498, etc.) for the customer.
tags:
- Tax
security:
- OAuth2: []
parameters:
- name: taxYear
in: query
schema:
type: integer
description: Filter by tax year
responses:
'200':
description: Tax form list
content:
application/json:
schema:
$ref: '#/components/schemas/TaxFormList'
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.tiaa.org/oauth2/authorize
tokenUrl: https://auth.tiaa.org/oauth2/token
scopes:
openid: OpenID Connect
profile: Customer profile
accounts: Account data access
transactions: Transaction data access
investments: Investment data access
tax: Tax document access
schemas:
AccountList:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/Account'
page:
$ref: '#/components/schemas/Page'
Account:
type: object
properties:
accountId:
type: string
description: Unique account identifier
accountType:
type: string
enum:
- INVESTMENT
- RETIREMENT
- ANNUITY
- BROKERAGE
description: Account type
displayName:
type: string
description: Human-readable account name
accountNumber:
type: string
description: Masked account number
balanceAsOf:
type: string
format: date-time
description: Balance timestamp
currentBalance:
type: number
format: double
description: Current account balance in USD
currency:
type: string
default: USD
status:
type: string
enum:
- OPEN
- CLOSED
- PENDING
TransactionList:
type: object
properties:
transactions:
type: array
items:
$ref: '#/components/schemas/Transaction'
page:
$ref: '#/components/schemas/Page'
Transaction:
type: object
properties:
transactionId:
type: string
accountId:
type: string
transactionType:
type: string
enum:
- CREDIT
- DEBIT
- DIVIDEND
- INTEREST
- CONTRIBUTION
- WITHDRAWAL
- TRANSFER
amount:
type: number
format: double
description:
type: string
transactionDate:
type: string
format: date-time
postedDate:
type: string
format: date-time
status:
type: string
enum:
- PENDING
- POSTED
PositionList:
type: object
properties:
positions:
type: array
items:
$ref: '#/components/schemas/Position'
Position:
type: object
properties:
positionId:
type: string
accountId:
type: string
symbol:
type: string
description: Security symbol or ticker
description:
type: string
quantity:
type: number
format: double
marketValue:
type: number
format: double
costBasis:
type: number
format: double
priceAsOf:
type: string
format: date-time
price:
type: number
format: double
currency:
type: string
default: USD
Customer:
type: object
properties:
customerId:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
phone:
type: string
addresses:
type: array
items:
$ref: '#/components/schemas/Address'
Address:
type: object
properties:
addressType:
type: string
enum:
- HOME
- MAILING
line1:
type: string
line2:
type: string
city:
type: string
state:
type: string
postalCode:
type: string
country:
type: string
TaxFormList:
type: object
properties:
taxForms:
type: array
items:
$ref: '#/components/schemas/TaxForm'
TaxForm:
type: object
properties:
taxFormId:
type: string
formType:
type: string
enum:
- 1099-R
- 5498
- 1099-INT
- 1099-DIV
taxYear:
type: integer
accountId:
type: string
issuedDate:
type: string
format: date
downloadUrl:
type: string
format: uri
Page:
type: object
properties:
nextOffset:
type: integer
totalElements:
type: integer
limit:
type: integer