Sorry, you need to enable JavaScript to visit this website.
Skip to main content

Credential Based Account Aggregation

Working with Datasets

What is a Dataset?

A dataset is a logical grouping of data attributes used for requesting a specific set of data from the data providers during add and refresh accounts.

Yodlee platform v1.1 supports four datasets: BASIC_AGG_DATA, ADVANCE_AGG_DATA, and ACCT_PROFILE. You can choose the dataset and attributes required for your business during the onboarding process.

  • Premium – Dataset attributes that require additional navigation to aggregate.
  • Sensitive – Dataset attributes like PII are sensitive and can be misused for fraudulent purposes. To subscribe to sensitive data, the audit or compliance criteria of the Yodlee Security Office have to be met.

Click the appropriate dataset tab to view the attributes-related details specific to the dataset:

Dataset Attributes Applicable Containers/Account Types Regions API Endpoints Fields
BASIC_ACCOUNT_INFO bank, investment, credit card, insurance, loan, reward, and bill. All regions GET/accounts
GET/accounts/{accountId}		 accountId
accountNumber
accountName
accountType
balance
availableBalance
ACCOUNT_DETAILS bank, investment, credit card, insurance, loan, reward, and bill. All regions GET/accounts
GET/accounts/{accountId}		 All attributes
TRANSACTIONS bank, investment, credit card, insurance, and loan All regions GET transactions All attributes
HOLDINGS investment and insurance All regions GET/holdings All attributes
STATEMENTS credit card, insurance, loan, and bill. All regions GET/statements All attributes
Dataset Attributes Applicable Containers/Account Types Regions API Endpoints Fields

INTEREST_DETAILS

 loan US GET/accounts
GET/accounts/{accountId}		 interestRate
interestRateType

PAYMENT_DETAILS

 loan US GET/accounts
GET/accounts/{accountId}		 payByDate
payoffAmount
outstandingBalance

COVERAGE

 investment and insurance US and Australia GET/accounts
GET/accounts/{accountId}		 type
startDate
endDate
amountType
limitType (applicable only for health insurance)
unitType (applicable only for health insurance)
cover
met(applicable only for health insurance)
Dataset Attributes Applicable Containers/Account Types Regions API Endpoints Fields
FULL_ACCT_NUMBER bank, investment, and loan US, UK, Canada, Australia, and India. GET/accounts
GET/accounts/{accountId}		 paymentAccountNumber
unmaskedAccountNumber
fullAccountNumber(deprecated)

BANK_TRANSFER_CODE

 bank and investment. US: Routing number
India: IFSC
Australia: BSB (Bank-StateBranch)
UK: Sort code sites in the United States.		 GET/accounts
GET/accounts/{accountId}		 bankTransferCode
HOLDER_NAME bank, loan, and investment. US, UK, Canada, Australia, and India. GET/accounts?include=holder,profile
GET/accounts/{accountId}?include=holder, profile		 holder.name
holder.ownershipType
HOLDER_DETAILS bank and investment. US, UK, Canada, Australia, and India.

GET/accounts?include=holder,profile
GET/accounts/{accountId}?include=holder, profile

GET providerAccounts/profile

 holder
profile
PAYMENT_PROFILE loan US GET/accounts, GET/accounts/{accountId} identifier
address
paymentBankTransferCode

Dependent Datasets

Certain datasets are retrieved even though they are not provided in the request. Following datasets are retrieved implicitly during the add, edit, and update/refresh account flows so the requested datasets can be retrieved successfully.

Requested Dataset Implicit Dataset Applicable Containers
ADVANCE_AGG_DATA.INTEREST_DETAILS BASIC_AGG_DATA.ACCOUNT_DETAILS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Loan
ADVANCE_AGG_DATA.PAYMENT_DETAILS BASIC_AGG_DATA.ACCOUNT_DETAILS
BASIC_AGG_DATA.BASIC_ACCOUNT_INFO		 Loan
ADVANCE_AGG_DATA.COVERAGE BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Investment
Insurance
ACCT_PROFILE.FULL_ACCT_NUMBER BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Bank
Investment
Loan
ACCT_PROFILE.BANK_TRANSFER_CODE BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Bank
Investment
ACCT_PROFILE.HOLDER_DETAILS ACCT_PROFILE.HOLDER_NAME
BASIC_AGG_DATA.BASIC_ACCOUNT_INFO		 Bank
Investment
ACCT_PROFILE.HOLDER_NAME BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Bank
Investment
ACCT_PROFILE.PAYMENT_PROFILE ACCT_PROFILE.FULL_ACCT_NUMBER
BASIC_AGG_DATA.BASIC_ACCOUNT_INFO		 Loan
BASIC_AGG_DATA.ACCOUNT_DETAILS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Bank
Investment
Credit Card
Insurance
Realestate
Loan Reward
Bill
BASIC_AGG_DATA.HOLDINGS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Investment
Insurance
BASIC_AGG_DATA.STATEMENTS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO Insurance
Loan
Bill
Credit Card
BASIC_AGG_DATA.ACCOUNT_DETAILS CreditCard

Choose Your Dataset Attributes

  • You have the flexibility to choose among the dataset attributes needed for your product flow.
  • You can configure the datasets to be retrieved by default and the datasets to be retrieved on demand.
  • During the onboarding process, work with the Yodlee support team to define your dataset configurations and containers.

Important Notes

  • Sensitive dataset attributes can be passed only if the same has been subscribed if not, an error will be returned.
  • If a dataset attribute or a container is not supported, an error will be returned.
  • If a data provider does not support some of the dataset attributes, then data only for the supported dataset attributes will be returned.
  • If a subscribed dataset attribute is requested for multiple containers, but the provider supports the attribute only for one container, the request will be honored for the supported container and the rest will be ignored.
  • If multiple subscribed dataset attributes are requested, but the provider does not support one of the dataset attributes, the request will be honored for the supported dataset and the rest will be ignored.
  • If multiple subscribed dataset attributes are requested but the provider does not support all the requested dataset attributes then an error will be returned.

APIs Accepting Datasets as Input

The following is the list of API services that accept dataset and dataset attributes:

Endpoint URL Input Parameter Impact
GET providers dataset Helps return all the provider sites supporting the provided datasets.
Helps search a site supporting the provided datasets.
Helps return the popular and suggested sites supporting the provided datasets
POST providerAccounts

PUT providerAccounts		 dataset

datasetName		 Indicates the data to be retrieved from the provider site that corresponds to the dataset name.
If not provided, the implicit dataset attributes have to be retrieved.

Link or Update Account API Implementation Flow Charts

End User Account Credential Encryption

The Yodlee platform serves a customer base of Financial Institutions and FinTech companies. The end-users of our customers can link their financial accounts (bank, brokerage, credit card accounts, etc.) to the Yodlee platform. Our customers then have a comprehensive and regularly updated view of their end-users’ financial assets and needs. The Yodlee platform also supports account verification on behalf of customers to confirm their end-users’ account ownership.

Yodlee supports linking an account through Yodlee APIs. These APIs accept sensitive and personally-identifiable information (PII), like account access credentials. Network communication to these APIs uses the industry-standard Transport Layer Security defined as part of the https protocol. 

In addition to encryption defined by the https protocol, Yodlee further protects end-user data by requiring account access credential data to be encrypted before uploading to a Yodlee server. 

What Data is Encrypted?

If you use your own code to link your end-users accounts to the Yodlee platform, and not the FastLink tool, you must encrypt the end-user credentials to access an online financial account before uploading them to Yodlee. These fields are provided with a loginForm entity type when calling the relevant APIs and are identified in the table below.

Fields Examples
formType=login & fieldType=password
  • Username/User ID
  • Password/Pin
formType=questionAndAnswer & fieldType=password Security answers for Multi-Factor Authentication questions

In the “add or edit credentials” flow of your browser or app, when not using FastLink, encrypt these fields (only) before passing the encrypted data to Yodlee.

Note: Do not encrypt OTP (formType: token) or CAPTCHA (formType: image).

Encryption is not supported in the Sandbox environment, and should not be done in apps under development there.  Encryption is supported in the Development and Production environments for all other pricing tiers (Launch, Grow, and Enterprise). 

Yodlee APIs Requiring Data Encryption

These two API calls are the ones that upload account credential data.  When you call either of these APIs to add or change credential data, you must first encrypt the credential data.

If the credentials need to be updated, you can first retrieve them using the Get Provider Account Details: GET /providerAccounts/{providerAccountId}?include=credentials API call. The credentials will be returned to you in decrypted (plain) form.

How to Encrypt Data

Yodlee uses the RSA algorithm to encrypt credential data and provides you with an RSA public key for this purpose. You can encrypt the data by writing a short computer program, starting from the Java example shown below. Alternatively, you can test the process and encrypt small amounts of data by using the interactive form on the RSA Encryption Utility page.


To encrypt data in software, follow these steps:

Step 1: Retrieve the Public Key

Retrieve your public key using the GET /configs/publicKey endpoint once per application session. When retrieved, the public key can be cached on one of your servers.

Sample Response

{
   "publicKey":{
      "alias":"03072_9",
      "key":"-----BEGIN PUBLIC KEY-----\r\nMIIBIjANBgkqhkiG9w0BAQEFAAOC\r\n-----END PUBLIC KEY-----"
   }
}

Note: The RSA key pair used to encrypt/decrypt credentials is separate and unrelated to the RSA key pair used for JWT token creation.

Step 2: Encrypt the User Credentials

To encrypt one field using the public key obtained in Step 1: Retrieve the Public Key:

  1. Convert the string named "keyAsPemString" to a key object. The string is an RSA public key in PEM format.
    PEM means “Privacy Enhanced Mail” and simply means the binary key has been encoded as one kind of base64 encoding to ensure it only contains printable ASCII characters.
  2. Encrypt the data using the options “RSA/ECB/PKCS1Padding” and the key object.
  3. Hex-encode the encrypted data as a string.
  4. Note that the sample response returned from step 1 included a string called “keyAlias”. In the example, the keyAlias has the value “03072_9”. Concatenate the literal value of the keyAlias string “03072_9” + “:” + the hex-encoded encrypted string to form the encrypted data for this field.

You may find it helpful to use the BouncyCastle open-source encryption library, which can be found at https://www.bouncycastle.org/. Bouncy Castle has code libraries for Java and C#. 

Here are the core steps in Java.

String keyAlias = "03072_9";
StringReader fileReader= new StringReader(keyAsPemString);
PEMReader pemReader= new PEMReader(fileReader);
PublicKey pk= (PublicKey)pemReader.readObject();
Cipher c = Cipher.getInstance ("RSA/ECB/PKCS1Padding");
c.init(Cipher.ENCRYPT_MODE, pk);
ciphertext = c.doFinal(cleartext.getBytes());
return keyAlias + ”:” + HexEncode.encode(ciphertext);

Step 3: Send the Encrypted User Credentials

In the “add or edit credential” flow, send the encrypted user credentials to the POST /providerAccounts or PUT /providerAccounts endpoints. All other details are similar to the non-encrypted “add an account or edit credentials” flow.

Sample Request:

{ 
   "field":[ 
      { 
         "id":"XXXXX",
         "value":"02122015_1:0472a89dbdfccad71ec34361d8585d0f77028197abfadc11bf0c0"
      },
      { 
         "id":"XXXXX",
         "value":"02122015_1:5d6643f0e861952a0580e4ddd48f3b1d17a2583edd2e9dc744a884e93b38b415de5e700a"
      }
   ]
}

Note: The encrypted data are known as “value” starts with the string “02122015_1:”. This is the keyAlias for this developer. The encrypted credential follows the colon. The keyAlias tells Yodlee which private key to use to decrypt the credential when you next ask for it.

Error Response

If the following response is received, the keys assigned to you have changed, so fetch and cache the keys again (Step 1: Retrieve the Public Key). The Http response status is 400 and the error message is below. The error message may contain additional fields and values.

{ 
  "errorCode": "Y400"
  "errorMessage": "Decryption failure for FieldInfo" 
}

Best Practices