Financial Data Exchange (FDX)
API and Data Structures Working Group
Version 4.1
April, 2020

FS-ISAC Traffic Light Protocol (TLP) Green: Recipients may share TLP GREEN information with peers, trusted government and critical infrastructure partner organizations, and service providers with whom they have a contractual relationship, who have a need-to-know but not via publicly accessible channels.

Change Log

1. Introduction

The Financial Data Exchange API and Data Structures (FDX API) enable Data Aggregators and Data Intermediaries to obtain consumer’s financial data from a financial platform provider. FDX API is intended to replace screen scraping as a preferred method for Data Aggregators and Data Intermediaries to obtain this data. Screen scraping is not secure as it requires consumers to share their financial platform login credential with Data Aggregators and Data Intermediaries. FDX API uses OAuth tokens which a consumer generates on the financial platform and provides to the Data Aggregators and Data Intermediaries. The tokens are then passed via FDX API to gain access to the consumer’s financial data.

1.1 Definitions

1.1.1 Consumer

• An individual or an agent, trustee, or representative acting on behalf of an individual with ownership rights to the data and transactional capabilities at a financial platform provider.

• The individual with ownership rights to the data. This can also mean parties the consumer delegates access to like: Spouse, Bookkeeper, CPA, Attorney, Investment Advisor

1.1.2 Data Access Point

• Consumer financial product and service providers that rely, at least in part, on consumer-permissioned access to consumer financial account data to display data from one or more sources to a consumer and in some instances facilitate transactional capabilities on behalf of the consumer.

• The presentation layer for the data to the Consumer. This can be an application, web page, or other medium.

1.1.3 Data Aggregator / Data Intermediary

• Entities that obtain consumer financial data directly from consumer financial platform providers for one or more data access points.

1.1.4 Financial Platform Provider

• Financial Institution’s System of Record (SOR) for Consumer financial data. This can be the FI itself or a Service Bureau or other party that maintains the SOR on behalf of the FI.

2. Ability Criteria

This section is now deprecated and will be relocated, TBD.

3. Deployment

In legacy OFX, a multitude of desktop PFM applications connect to a multitude of OFX servers. In FDX API, this is replaced with a service bus model.

Data Aggregators and Data Intermediaries will consolidate requests from all application clients into a single FDX API client. The Financial platform provider’s API server will authenticate and direct the incoming requests to the appropriate backend server.

4. Message Transport

The FDX API requires the use of HTTPS, which is a reliable synchronous stateless message protocol. REST is preferred because it decouples the message syntax from the transport concerns. REST supports content type negotiation, conditional fetches, and compression. Since confidential information is being exchanged, all interactions must be encrypted with TLS.

5. Service Delivery Expectations

The FDX API server response to requests must start within 30 seconds. The server may use HTTP 100 continue or 200 chunked encoding response to extend the response time for large data sets. Server responses should not last longer than 120 seconds to prevent long running transactions.

6. Message Syntax

The FDX API only supports JSON syntax options, with the exception of image file responses.

7. Security

Please refer to the Financial Data Exchange Aggregation Services Working Group’s document “Control Considerations for Consumer Financial Account Aggregation Services - Reference Security Architecture and Standard Specification” Version 2.1 – June 2018 for securing FDX API.

Sections “Component Model: Guidelines for Authentication and Aggregation Data Feeds” and “Deployment Model: Implementation Specifications / Technology” are of special interest as you look secure FDX APIs.

7.1 Token Scope

The FDX API client application will include a list of desired scopes when requesting an authorization token. The following scopes are defined for FDX API data service.

The FDX API server will return the list of allowed scopes with the issued authorization token. The FDX API server may limit the scopes for the purpose of not implementing certain APIs.

The FDX API server may also present scopes in the access confirmation page after end user login to have them determine each account(s) access for the requesting application.

8. Logical Data Model

FDX API will eventually encompass multiple financial data domains. At this point, entities and messages are required to support the aggregation of personal financial data.

8.1 Entity Identity

The User entity is not expressed in FDX API messages. The Login entity has an identity unique to its owning Institution. The Login identity is usually the username part of a username / password login. The Login surrogate identity is the OAuth token obtained from the Financial Institution. The Account entity has an identity that is unique to the owning Institution. The Transaction entity has an identity that is unique to the owning Account and is usually unique to the owning Institution.

The entity identity (or surrogate identity) is required when transmitting the entities and is used to relate the entities. The FDX API identity properties have a maximum of 256 characters. (IBAN account identifiers are 31 characters, ACH has 9 digits for routing,17 digits for account number, and SHA-256 generates an almost-unique 256-bit (32-byte) signature for a given text.)

8.2 Surrogate Identity

OAuth creates a surrogate identity for a Login – a FDX API server does not expose the financial institution’s principal identity of the Login. To limit the exposure of personally identifiable information, the other identities transmitted by the FDX API server should be a surrogate identity. Surrogates must provide the same uniqueness constraints on the entity relationships as described above. Any surrogate identities must be long term persistent.

If the Financial platform provider’s account identity is considered confidential, a surrogate identity should be used (AccountId should not equal AccountNumber).

9. Residual Data

Residual data is defined as data that is no longer being used, for example if an account has been closed. Data Aggregators should delete residual data from their systems within 180 days.

10. Protocol

The FDX API client requests data using HTTP GET, POST and PUT) methods. The request includes an appropriate Request-URI. Requests must include an OAuth token in the authorization header. The following is a sample of the headers provided in a typical request.

GET /accounts HTTP/1.1
Host: example.com
Authorization: Bearer w0mcJylzCn-AfvuGdqkty2-KP48=
Accept: application/json
Accept-Charset: UTF-8 Accept-Encoding: gzip

The FDX API server will use HTTP status codes to indicate the success or failure of a request. Response code details specific to FDX API follow. For status codes other than 200, the HTTP response body must contain an Error Entity.

10.1 Headers

10.1.1 Transport Security

All FDX API communication must be secured from network sniffing with SSL/TLS. Using TLS will secure the entire request and response including any headers. We recommend that both the FDX API client and server use certificates. Additionally, FDX API server responses should include Cache-Control headers

Cache-Control: no-cache, no-store

to prevent any caching or storing of the response.

10.1.2 Request Authorization

The FDX API client does not identify a User to the FDX API server. Instead, the User’s financial institution Login is implied via an OAuth token. The data returned by any FDX API request is limited to what the User could see using his/her Login and further limited by the scope of the OAuth token.

The FDX API client uses the Authorization request header with a Bearer or MAC token. Bearer tokens are recommended although the server has option to issue MAC tokens as an alternative if the client supports it. How to obtain this token was detailed in the Security Model section.

Authorization: Bearer w0mcJylzCn-AfvuGdqkty2-KP48=

10.1.3 Content Negotiation

The FDX API clients and servers use standard HTTP headers to negotiate transport options.

The FDX API client uses the Accept request header to ask for its preferred syntax. The server must respond with one of the requested syntaxes or with a 406 status code.

Accept: application/json

The FDX API client uses the Accept-Charset request header to ask for its preferred character set. The server must respond with the body encoded in one of the requested character sets or with a 406 status code.

Accept-Charset: UTF-8

The FDX API server uses the Content-Type response header to inform the client of the response syntax and charset.

Content-Type: application/json; charset=UTF-8

The FDX API client uses the Accept-Encoding request header to ask for its preferred compression encoding. The server must either respond with the body compressed with one of the requested compressions, or with the body not compressed.

Accept-Encoding: compress, gzip

The FDX API server uses the Content-Encoding response header to inform the client of the response encoding.

Content-Encoding: gzip

For queries, the FDX API client may use the If-Modified-Since request header to ask for a data response only if the data has been modified since the given date. If the server supports this header and the data has not been modified, a 304 HTTP response code will be returned to the client.

If-Modified-Since: Wed, 12 Sep 2012 06:00:00 GMT

10.1.4 Server Environment

The FDX API server returns a Date header with every response.

Date: Tue, 11 Sep 2012 19:43:31 GMT

10.1.5 Host

The Host request header field specifies the Internet host and port number of the resource being requested. A Host header without any trailing port information implies the default port for the service requested (e.g. “80” for an HTTP URL).

Host: example.com

10.1.6 Client Identity

The FDX API client supplies a User-Agent header with every request. This header should not be used to change the content of the response. This header is designed to only collect statistics on the products using the FDX API data service. The first token is the Data Aggregator and Data AccessPoint version. The second token is the product and product version.

User-Agent: Example/1.2.3 Crawler/4.3.1

10.1.7 Customer’s Last Login Time

The FDX API client can optionally supply the last time the customer logged into the Data Aggregator product if this data is available.

FDX-CustomerLastLoggedTime: Tue, 11 Sep 2012 19:43:31 GMT

10.1.8 Customer’s IP Address

The FDX API client optionally can supply the customer’s IP address if this data is available or applicable.

FDX-CustomerIPAdress: 0.0.0.0

10.1.9 Interaction Tracking

The FDX API client uses the FDX API-InteractionId request header to inform server of an interaction tracing identifier. A FDX API-InteractionId is unique to an FDX API client instance. The FDX API-InteractionId allows support people to trace a full path of interactions through multiple sub-systems. The FDX API server must include the value of this header and the client identifier in any logs.

FDX-InteractionId: byx24A1a111

The FDX API server uses the FDX API-InteractionId response header to inform the client of the response FDX API-InteractionId. The FDX API-InteractionId value must be same as the corresponding client request header value.

FDX-InteractionId: byx24A1a111

10.1.10 Financial Institution Identification

If the FDX API service is provided by a service bureau which uses the same end point for multiple institutions, the FDX API client must provide a header the identifies the desired financial institution. The service bureau defines this value. For example, it is often the financial institution’s routing number (RTN).

FDX-FinancialId: 123456789

10.2 Errors

When FDX API servers are unable to fulfill a request, they should send Error Entity as the response payload along with an appropriate HTTP Status Code. Error messages should contain just enough information for an end user to understand what went wrong without compromising security.

11. Pagination

The FDX API uses cursor-based pagination by leveraging an opaque cursor in the response that can point to an offset in the collection of records being paginated. This leverages the defacto pagination query parameters in the request:

• limit an optional field to specify the maximum number of elements that the consumer wishes to receive in a single call. Providers should implement reasonable defaults and maximum. Providers can use time based limits where the result set might be less then the limit and each page could contain a different number of elements.
• offset an optional field to specify an opaque cursor used to retrieve a portion of the requested data

The response will be a “mixin” with PaginatedArray. The response will contain a links key of type PageMetadataLinks and a page key of type PageMetadata. The key fields returned are as follow:

• page.nextOffset is an opaque identifier used to retrieve the next page of results
• page.prevOffset is an opaque identifier used to retrieve the previous page of results
• page.totalElements contains the number of total elements matching the query
• links.next.href represents the URL used to retrieve the next page. This URL should contain the original parameters of the search query such as startDate and endDate if applicable
• links.prev.href represents the URL used to retrieve the previous page. This URL should contain the original parameters of the search query such as startDate and endDate if applicable

The client should look for page.nextOffset or links.next.href to determine if additional API calls are required to retrieve the data requested. The client should continue to make API calls until the key is no longer returned in the response.

Note

• The offset query parameter is a cursor for the collection to index from. It could be number or an opaque string. If it is a number it is SHOULD use a 0 based index.
• The optional limit query parameter indicates the number of records that is requested by the client. The API server SHOULD have reasonable defaults.

11.1 Sample implementation

GET /accounts?limit=10

11.1.1 Initial Response

{
  "page":{
    "nextOffset": "nextoffset@10",
    "totalElements": 100
  },
  "links":{
    "next": {"href":"/accounts?offset=nextoffset@11&limit=10"}
  },
  "accounts":[
    {"accountId": "1", "nickname": "Account 1"},
    {"accountId": "2", "nickname": "Account 2"},
    {"accountId": "3", "nickname": "Account 3"},
    {"accountId": "4", "nickname": "Account 4"},
    {"accountId": "5", "nickname": "Account 5"},
    {"accountId": "6", "nickname": "Account 6"},
    {"accountId": "7", "nickname": "Account 7"},
    {"accountId": "8", "nickname": "Account 8"},
    {"accountId": "9", "nickname": "Account 9"},
    {"accountId": "10", "nickname": "Account 10"}
  ]
}

11.1.2 Final Response

{
  "page":{
    "prevOffset": "prevoffset@81",
    "totalElements": 100
  },
  "links":{
    "prev": {"href":"/accounts?offset=prevoffset@81&limit=10"}
  },
  "accounts":[
    {"accountId": "91", "nickname": "Account 91"},
    {"accountId": "92", "nickname": "Account 92"},
    {"accountId": "93", "nickname": "Account 93"},
    {"accountId": "94", "nickname": "Account 94"},
    {"accountId": "95", "nickname": "Account 95"},
    {"accountId": "96", "nickname": "Account 96"},
    {"accountId": "97", "nickname": "Account 97"},
    {"accountId": "98", "nickname": "Account 98"},
    {"accountId": "99", "nickname": "Account 99"},
    {"accountId": "100", "nickname": "Account 100"},
  ]
}

• Since this is the last page, page.nextOffset and links.next.href are not returned in the response. This indicates to the client that no further pages are available.
• The response attribute prev identifies the previous page url and offset.

12. Resources

When implementing FDX API, client and server maintainers must agree on the data service endpoint. All resource URIs may be prefixed by a base URI, for example https://api.fi.com/fdx/v4. The base URI should include the version of FDX API that the server implements.

12.1 /accounts

12.2 /accounts/{accountId}

12.3 /accounts/{accountId}/statements/{statementId}

12.4 /accounts/{accountId}/statements

12.5 /accounts/{accountId}/transaction-images/{imageId}

12.6 /accounts/{accountId}/transactions

12.7 /availability

12.8 /capability

12.9 /customers/current

12.10 /transfers

12.12 /transfers/{transferId}/status

12.13 /tax-forms

12.14 /tax-forms/{taxFormId}

12.15 POST /tax-forms

12.16 PUT /tax-forms/{taxFormId}

13. Versioning

APIs should be designed for change to expose new behavior or data. Non-breaking (backward compatible) service changes are denoted by minor versions (e.g. v1 moves to v1.1) while breaking changes (not backward compatible) are denoted by a major version (e.g. v1 moves to v2). When minor versions of services are released they are backward compatible so the services released in place of the existing service. When major versions of services are released there are multiple versions of the same service available at the same time. The reason for a new service version is because some major piece of functionality has changed in the service and consumer of the previous version should be motivated to adopt the new version. We realize that quick movement to the new service will not always happen. Therefore, we recommend that no more than three approved major versions of a service exist at any one time. When a fourth major version is released into production the oldest version will be considered deprecated and scheduled for retirement within a period not to exceed 12 months.

14. Entities

Entities are specified in the accompanying FDX API Specification document fdxapi4.yaml.

14.1 Account Entity

An abstract account entity that concrete account entities extend. Extends and inherits all fields from AccountDescriptor.

14.2 AccountDescriptor Entity

Minimal information about the account for use in lightweight arrays.

14.3 AccountDescriptorList Entity

A lightweight array of accounts.

14.4 Accounts Entity

An optionally paginated array of accounts.

14.5 AccountDetailsRequest Entity

14.6 Availability Entity

14.7 Capability Entity

Describes capabilities of this implementation of FDX API.

14.8 Contribution Entity

14.9 Currency Entity

14.10 Customer Entity

14.11 CustomerName Entity

The name of an individual in their role as a customer. Inherits and extends all of IndividualName.

14.12 DebtSecurity Entity

14.13 DeliveryAddress Entity

A delivery address and its location type. Inherits and extends all of Address.

14.14 DepositAccount Entity

Extends and inherits all fields from Account.

14.15 DepositTransaction Entity

Extends and inherits all fields from Transaction.

14.16 Error Entity

An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account.

14.17 FiAttribute Entity

Financial platform provider-specific attribute.

14.18 FiPortion Entity

14.19 Holding Entity

14.20 InvestmentAccount Entity

Extends and inherits all fields from Account.

14.21 InvestmentBalance Entity

14.22 InvestmentLoan Entity

14.23 InvestmentTransaction Entity

Extends and inherits all fields from Transaction.

14.24 LineItem Entity

14.25 LoanAccount Entity

Extends and inherits all fields from Account.

14.26 LoanTransaction Entity

Extends and inherits all fields from Transaction.

14.27 LocAccount Entity

Extends and inherits all fields from Account.

14.28 LocTransaction Entity

A line of credit transaction. Extends and inherits all fields from Transaction.

14.29 MutualFundSecurity Entity

14.30 OpenOrder Entity

14.31 OptionSecurity Entity

14.32 OtherSecurity Entity

14.33 PaymentDetails Entity

14.34 PlannedAvailability Entity

14.35 Portion Entity

14.36 SingleAccountDetailsRequest Entity

14.37 Statement Entity

14.38 Statements Entity

Array of Statement entities, inherits and implements PaginatedArray

14.39 StockSecurity Entity

14.40 SweepSecurity Entity

14.41 TaxLot Entity

14.42 TelephoneNumber Entity

Telephone subscriber number defined by ITU-T recommendation E.164

14.43 Transaction Entity

14.44 Transactions Entity

Array of transactions, implements PaginatedArray

14.45 Transfer Entity

14.46 TransferStatus Entity

14.47 Vesting Entity

14.48 InsuranceAccount Entity

Inherits and extends Account.

14.49 InsuranceTransaction Entity

An Insurance transaction, inherits and extends Transaction

14.50 Bills Entity

14.51 PensionSource Entity

14.52 AnnuityAccount Entity

14.53 HateoasLink

14.54 PageMetadataLinks

14.55 PageMetadata

14.56 PaginatedArray

To be used as a mixin using “allOf”

14.57 Tax1041K1

Beneficiary’s Share of Income, Deductions, Credits, etc. Extends and inherits all fields from Tax.

14.58 Tax1065K1

Partner’s Share of Income, Deductions, Credits, etc. Extends and inherits all fields from Tax.

14.59 Tax1095A

Health Insurance Marketplace Statement. Extends and inherits all fields from Tax.

14.60 Tax1095B

Health Coverage. Extends and inherits all fields from Tax.

14.61 Tax1095C

Employer-Provided Health Insurance Offer and Coverage. Extends and inherits all fields from Tax.

14.62 Tax1097Btc

Bond Tax Credit. Extends and inherits all fields from Tax.

14.63 Tax1098

Mortgage Interest Statement. Extends and inherits all fields from Tax.

14.64 Tax1098C

Contributions of Motor Vehicles, Boats, and Airplanes. Extends and inherits all fields from Tax.

14.65 Tax1098E

Student Loan Interest Statement. Extends and inherits all fields from Tax.

14.66 Tax1098T

Tuition Statement. Extends and inherits all fields from Tax.

14.67 Tax1099A

Acquisition or Abandonment of Secured Property. Extends and inherits all fields from Tax.

14.68 Tax1099B

Proceeds from Broker and Barter Exchange Transactions. Extends and inherits all fields from Tax.

14.69 Tax1099C

Cancellation of Debt. Extends and inherits all fields from Tax.

14.70 Tax1099Cap

Changes in Corporate Control and Capital Structure. Extends and inherits all fields from Tax.

14.71 Tax1099Div

Dividends and Distributions. Extends and inherits all fields from Tax.

14.72 Tax1099G

Certain Government Payments. Extends and inherits all fields from Tax

14.73 Tax1099H

Health Coverage Tax Credit (HCTC) Advance Payments. Extends and inherits all fields from Tax

14.74 Tax1099Int

Interest Income. Extends and inherits all fields from Tax.

14.75 Tax1099K

Merchant Card and Third-Party Network Payments. Extends and inherits all fields from Tax

14.76 Tax1099Ltc

Long-Term Care and Accelerated Death Benefits. Extends and inherits all fields from Tax

14.77 Tax1099Misc

Miscellaneous Income. Extends and inherits all fields from Tax.

14.78 Tax1099Oid

Original Issue Discount. Extends and inherits all fields from Tax.

14.79 Tax1099Patr

Taxable Distributions Received From Cooperatives. Extends and inherits all fields from Tax.

14.80 Tax1099Q

Payments from Qualified Education Programs. Extends and inherits all fields from Tax.

14.81 Tax1099R

Distributions from Pensions, Annuities, Retirement or Profit-Sharing Plans, IRAs, Insurance Contracts, etc. Extends and inherits all fields from Tax.

14.82 Tax1099S

Proceeds from Real Estate Transactions. Extends and inherits all fields from Tax.

14.83 Tax1099Sa

Distributions from an HSA, Archer MSA, or Medicare Advantage MSA. Extends and inherits all fields from Tax.

14.84 Tax1120SK1

Shareholder’s Share of Income, Deductions, Credits, etc. Extends and inherits all fields from Tax.

14.85 Tax2439

Notice to Shareholder of Undistributed Long-Term Capital Gains. Extends and inherits all fields from Tax.

14.86 Tax5498

IRA Contribution Information. Extends and inherits all fields from Tax.

14.87 Tax5498Esa

Coverdell ESA Contribution Information. Extends and inherits all fields from Tax.

14.88 Tax5498Sa

HSA, Archer MSA, or Medicare Advantage (MA) MSA Information. Extends and inherits all fields from Tax.

14.89 TaxW2

Wage and Tax Statement. Extends and inherits all fields from Tax.

14.89 TaxW2G

Certain Gambling Winnings. Extends and inherits all fields from Tax.

14.90 Tax

14.91 TaxDataForQR

Tax data container for QR Code purposes. Inherits and extends all of TaxData.

14.92 TaxData

Tax data container for API. Contains one and only one of the listed forms.