This migration document explains the various steps that are involved in migrating or upgrading to the fully RESTful Yodlee core API version 1.1.
This document also explains the new terminologies, new features, and deprecated features of legacy requests, alternative steps for critical flows that the Yodlee core API version 1.1 recommends.
The Envestnet | Yodlee financial data platform, through RESTful requests, provides developers access to over 14,000 data sources for a financial data, including bank direct deposit accounts (DDAs), wealth, credit card, loans, insurance, bills, small business, and more. Integration and seamless access to data enable developers that use our platform the ability to deliver rich user experiences.
Envestnet | Yodlee has released two versions of RESTful Yodlee core APIs:
FieldNames
Containers
Container to Site Based aggregation - Migration
Status/Error Code Migration
Our legacy API had error codes and a status field exposed to indicate the progress and the state of the add/update account process. There used to be multiple errors codes for similar errors, which didn’t provide much value to the developers. These similar error codes will only help the Yodlee teams debugging the issue in an efficient way.
To provide a better and smoother implementation experience in Yodlee's core API 1.1 version, there were significant enhancements made on providing a meaningful status to the provider accounts and accounts during the add/update process. Hence the accounts that were added using requests other than the Yodlee 1.1 API haveto undergo a data migration process. This will help providing a consistent API responses for the already added provider account and accounts. Yodlee's team will be involved in migrating the data.
The following fields are stopped from support in the Yodlee core API.
Linking/Update Accounts
In our legacy API, following were two sets of requests used for aggregating data from provider sites:
Yodlee has classified the aggregation data in to four major datasets. They are as follows:
Note: Customers can also request basic aggregation data and account profile in one request.
Link Account
Following are the API mappings and sequence that are called in the Add account implementation:
Updating Accounts
Add/Update Account Process Status
With the legacy requests, you would have used the errorCode and the status field at the mem site account level to display success or error message information to the users.
In case of Yodlee's core API 1.1, following are the two fields that has to be considered for implementation and knowing the data retrieval state:
providerAccount.status and dataset.additionalStatus that are returned in the PUT and POST providerAccounts should be used for the different states that the provider accounts enter into.
Please refer the different additionalStatus values that are provided at account level and provider account level. Use them per your solution needs and user experience that you want to offer to your end users.
Amounts/Money attributes in requests like accounts, transactions, holdings, etc. are not converted and are given as they are retrieved from the provider site or provided by the user.
Summary amounts in the requests under the derived endpoint are converted to the user’s preferred currency using currency conversion rates.
If the user has no preferred currency set, the summary amounts are converted to cobrand’s preferred currency.
Localization
Localization is performed for the following attributes:
Account types support in the Yodlee platform is extended to the following two account types:
The account deduplication feature prevents storage of duplicate account information in the Yodlee system by checking if the account is already aggregated or is a new account. This ensures only one instance of a user’s account is available in the Yodlee system.
An account will be mapped to one primary providerAccount and the other associated providerAccounts will be in the associatedProviderAccountId attribute of the GET accounts API response.
Re-adding of Accounts
Re-adding accounts with the same set of credentials using Yodlee APIs or Yodlee FastLink should be encouraged only to retrieve deleted accounts. An account should not be re-added to edit the provider accounts’ credentials or to refresh the account to retrieve the latest account information.
Dataset Requesting Capabilities
In Yodlee core API version 1.1, Yodlee has introduced flexibility to mandate the retrieval of existing data attributes that are specifically required for your business flow. As Yodlee incurs additional cost to retrieve the following information from pages other than the landing page, you will have to subscribe for the dataset attributes if they are critical for your business flow:
REFRESH Webhooks Notifications
Unlike legacy requests, the RESTful Yodlee core API has webhooks support to indicate the customers on the progress of add account, edit account and update account flows. This eliminates the need of polling the requests at frequent intervals. Refer to the developer portal to learn more about webhooks and the implementation details.
Data Extracts Implementation
If the customers are using the legacy Yodlee core API and had implemented synchronized data extracts, your implementation has to be replaced with the RESTful Yodlee core API. Refer to the data extracts page for more information and implementation details.
We also have built the data extracts feature with webhooks notification capability.
PKI Encryption
PKI Encryption allows enhanced secure handling of sensitive data during the Link Account processes. Yodlee recommends that developers use PKI encryption when they migrate to the RESTful Yodlee core API.
Customers have to encrypt the credentials and the answers for their questions before they send the same to Yodlee, if they turn on PKI. If customers use Yodlee FastLink, the PKI encryption will be taken care of by Yodlee. For more details, refer to the Yodlee API with PKI Feature page.
Closed Accounts
With the introduction of Yodlee's core API, Yodlee supports the ability to identify an account as a closed account. The status field of the account entity reflects the state.
Developers can request their users to confirm whether the account is closed when the status is “To be closed”. On receiving user confirmation, POST accounts/{accountId} API has to be invoked to update the account status as closed.
Larger Transaction History
Yodlee provides up to 365 days of a consumer's transaction data when adding an account when the data is available at the financial institution's site. Because fetching all the transaction data takes time, Yodlee has introduced the progressive refresh feature: one large response is broken into multiple small responses whenever required; this is a Yodlee internal process.
Yodlee progressive refresh is helpful in account addition scenarios when the data gathering process fails due to slow financial institution sites or there is a huge volume of consumers’ transaction data. For more details about the feature, refer to the Progressive Refresh for 365 Days of Transaction Data page.
Following are the new data aggregation capabilities that are available with the Yodlee core API 1.1:
This document also explains the new terminologies, new features, and deprecated features of legacy requests, alternative steps for critical flows that the Yodlee core API version 1.1 recommends.
Introducing Yodlee's Core API
Yodlee's core API is a modern RESTful API that offer a simple, intuitive and secure way for developers to access the Envestnet | Yodlee financial data platform. Our core value is not just to be the leader in providing financial data but also to deliver a world class developer experience.The Envestnet | Yodlee financial data platform, through RESTful requests, provides developers access to over 14,000 data sources for a financial data, including bank direct deposit accounts (DDAs), wealth, credit card, loans, insurance, bills, small business, and more. Integration and seamless access to data enable developers that use our platform the ability to deliver rich user experiences.
Envestnet | Yodlee has released two versions of RESTful Yodlee core APIs:
- Version 1.0 - released in Dec 2015
- Version 1.1 - released in Dec 2017
Terminology
Most of the input and the response parameters can be related and are self-explanatory. Following are the terms which the customers should know while they upgrade from the legacy API to Yodlee's core API.FieldNames
| Legacy API – FieldNames | Yodlee's Core API - FieldNames |
|---|---|
| memSiteAccount | providerAccount |
| memSiteAccId | providerAccountId |
| Site | provider |
| itemAccountId | accountId |
| itemAccounts | accounts |
Containers
| Legacy API –Container Names | Yodlee Core API – Container Names |
|---|---|
| Bank | bank |
| Bills | bill |
| credits | creditCard |
| insurance | insurance |
| Stocks | investment |
| Loans | loan |
| Miles | reward |
| mortgage | loan |
Data Migration
Data migration is a pre requisite activity a legacy API customer’s existing data should undergo before they move to Yodlee's core API 1.1 version.Container to Site Based aggregation - Migration
Yodlee introduced the concept of site-based account linking in 2013. Consumers provide the site they want to add and Yodlee takes care of adding all the accounts the consumer has at that site across all containers. This replaced the earlier version of container-based account linking where the consumer needed to explicitly add the same site multiple times until all accounts across all Containers were added.If the customers are already into site based aggregation, this step could be skipped.
If the customers are into container based aggregation, this step is a prerequisite for invoking RESTful Yodlee API services. Yodlee's team will need to be engaged for migration of the data.
As part of the migration to the current API version, we are consolidating user accounts based on the credentials used when the account was added. The consolidation is done by creating a new record called “memSiteAcc/providerAccount”. Then all the user’s items having the same credentials are associated with that single memSiteAccId/providerAccountId.
There is a possibility that an end user may mistakenly add some accounts multiple times. Account de-duplication is not available for container-based aggregation. In this case, we will create multiple items for the same accounts. Please note that a user who repeats account addition for the same container will create duplicate accounts under that memSiteAcc/providerAccount.
Customers migrating to YSL API version 1.1 should be alert to the need to work with their end users to keep the relevant account and discard the duplicates. Please use your regular Yodlee support channel if you need more information or assistance.
Status/Error Code Migration
Our legacy API had error codes and a status field exposed to indicate the progress and the state of the add/update account process. There used to be multiple errors codes for similar errors, which didn’t provide much value to the developers. These similar error codes will only help the Yodlee teams debugging the issue in an efficient way.
To provide a better and smoother implementation experience in Yodlee's core API 1.1 version, there were significant enhancements made on providing a meaningful status to the provider accounts and accounts during the add/update process. Hence the accounts that were added using requests other than the Yodlee 1.1 API haveto undergo a data migration process. This will help providing a consistent API responses for the already added provider account and accounts. Yodlee's team will be involved in migrating the data.
Deprecated fields
Customers have to change their implementation, if they are using a deprecated field. Please contact Yodlee team in case you need any guidance on the alternative implementation.The following fields are stopped from support in the Yodlee core API.
| Field Names | Reason | Alternative Recommendations for Critical Flows: |
|---|---|---|
| ItemId | This field is relevant only for container based aggregation. As Yodlee has moved from container-based aggregation to site-based aggregation there is no value add in exposing the item field. |
To know account/site level status during add/update: The status of accounts will be available at account level. Get accounts service should be used to pull the accounts data. The status at provider/site level can be known from get provider account detail service data. To trigger update(refresh) account flow: Retrieving up-to-date information of aggregated accounts can be achieved using the Update provider account service. |
| contentServiceId | This field is relevant only for the container based aggregation model. In the RESTful Yodlee API, as only the site based aggregation is supported, this field is killed. |
providerId indicates unique identifier for site. To get all supported sites: Get all providers service should be used to retrieve the supported sites or search for sites. To get the loginform of a site: Get provider detail service should be used to retrieve the login form of a site. |
| errorCode | This field is used to convey the status of aggregation. 0 indicates success or failure at container level. Non-zero code indicates occurrence of error. |
To know account/site level status during add/update: The error at accounts level can be known from dataset.additionalDataset field under accounts entity. Get accounts service should be used to pull the error information. The error at provider account level can be known from status field under provider accounts entity. Get provider account detail service should be used to pull the error information. |
Legacy API Vs Yodlee API
The flow diagram below illustrates the current API flow to authenticate the Yodlee server, authenticate or register a new user, allow the user to link their account, and then allow the user to view their account details.
The sections below highlight the differences between the API calls for each of these capabilities.
Authentication- SAML-based Authentication - To invoke the Yodlee APIs using the SAML-based authentication, you can continue to use the cobrand session and the user session tokens.
Use of Yodlee's core API requires customer login (referred as cobrand login) and user login. Cobrand login establishes authentication for the customer’s application with the Yodlee platform. User login allows customers to use requests for their end users.Capability Legacy API Service Yodlee's core API Service Cobrand login POST /authenticate/coblogin POST cobrand/login User login POST /authenticate/login POST user/login
POST user/SAMLLogin - API Key-based Authentication - Use the API Key-based authentication if you are not using the SAML-based authentication to invoke the Yodlee APIs. The user login and cobrand login endpoints are deprecated for API Key-based authentication.
Some of the key terminology in order to access Yodlee APIs using the API Key-based authentication mechanism follow: - API Key – The API key is the identifier of the cobrand and will be assigned to you when you sign a contract with Yodlee. This API key should be used to generate an Authentication token that will be used to access Yodlee APIs. If required, this API key can be revoked and a new key can be generated.
- Token – The JSON Web Token (JWT) must be signed using the RS512 algorithm to make sure it is secure. The JWT token should contain information about the API key and a user identifier. Also, this JWT token will have to be signed using your own private key and should be passed as an Authentication header with every API call.
- Public and Private Key – A public key of your private/public key pair will have to be uploaded to the Yodlee Developer Portal. This private key will have to be used to sign your token so that Yodlee servers can validate the token and make sure it is coming from a legitimate source.
Linking/Update Accounts
In our legacy API, following were two sets of requests used for aggregating data from provider sites:
- Aggregation requests – This is to retrieve accounts, statements, holdings and transactions.
- IAV(Instant Account Verification) requests – This is to retrieve full account number, routing number and holder details.
Yodlee has classified the aggregation data in to four major datasets. They are as follows:
- BASIC_AGG_DATA
- ADVANCE_AGG_DATA
- ACCOUNT_PROFILE
- DOCUMENTS
| Legacy API Service | Yodlee's Core API v1.1 Service |
|---|---|
| Aggregation requests retrieve: accounts, transactions, holdings, statements | If a customer needs accounts, transactions, holdings or statements, the customer should request BASIC_AGG_DATA dataset. |
| IAV requests retrieve: basic account information, full account number, holding name, routing number. | If a customer needs full account number, holding name and routing number, the customer should request ACCOUNT_PROFILE dataset. |
Link Account
Following are the API mappings and sequence that are called in the Add account implementation:
| Capability | Legacy API Service | Yodlee's Core API V1.1 Service |
|---|---|---|
| Locate Site | GET SiteTraversal/getAllSites | GET providers |
| Search Site | GET SiteTraversal/searchSite |
GET providers Note: Search text to be passed as query parameter for performing search. |
| Capture Credentials from user by displaying the site login form. | GET SiteTraversal/getSiteInfo | GET providers/{providerId} |
| Submit Credentials to Yodlee | POST SiteAccountManagement/addSiteAccount1 | POST providerAccounts |
| Check status OR wait for status change notification | GET Refresh/getSiteRefreshInfo |
GET providerAccounts/{providerAccountId} Note: requestId provided in the response of POST provider accounts should be provided to know the status of an add account progress, as that gives relevant and contextual information. Alternatively, instead of calling this polling API to learn the status, customers can also subscribe for webhooks and wait for notifications. For more details, refer to the Refresh Event page. |
| Submit MFA(if required) | PUT Refresh/putMFARequestForSite |
PUT providerAccounts Note: This step is applicable for MFA account only and is used to provide MFA information from the user. |
| check for status OR wait for status notification. | GET Refresh/getMFAResponseForSite |
GET providerAccounts/{providerAccountId} Note: requestId provided in the response of POST provider accounts should be provided to know the status of an add/update account progress, as that gives relevant and contextual information. |
| View Results |
GET /account/summary/all GET DataService/getItemSummariesForSite |
GET accounts |
| Capability | Legacy API Service | Yodlee's Core API V1.1 Service |
|---|---|---|
| Choose a Site to Edit |
GET /account/summary/all GET DataService/getItemSummariesForSite |
GET accounts |
| View/retrieve stored credentials | GET SiteTraversal/getSiteloginform |
GET providerAccounts/{providerAccountId} Note: include=credentials parameter should be passed to retrieve the credentials that are stored in the system |
|
Submit edited Credentials by user to Yodlee |
SiteAccountManagement/updateSiteAccountCredentials | PUT providerAccounts |
| Check status OR wait for status change notification | GET Refresh/getSiteRefreshInfo |
GET providerAccounts/{providerAccountId} Note: requestId provided in the response of PUT provider accounts should be provided to know the status of an update account progress, as that gives more relevant information. Alternative Approach: Alternatively, instead of calling this polling API to learn the status, customers can also subscribe for webhooks and wait for notifications. For more details, refer to the Refresh Event page. |
| Submit MFA(if required) | PUT Refresh/putMFARequestForSite | PUT providerAccounts |
| check for status OR wait for status change notification | GET Refresh/getMFAResponseForSite |
GET providerAccounts/{providerAccountId} Note: requestId provided in the response of PUT provider accounts should be provided to know the status of an update account progress, as that gives relevant and contextual information. |
|
View Results |
GET /account/summary/all GET DataService/getItemSummariesForSite |
GET accounts |
Updating Accounts
| Capability | Legacy API Service | Yodlee's Core API V1.1 Service |
|---|---|---|
| Choose a Site to update | GET /account/summary/all | GET accounts |
| Initiate Update | POST Refresh/startSiteRefresh | PUT providerAccounts |
| Check Update Account Status | GET Refresh/getSiteRefreshInfo | GET providerAccounts/{providerAccountId} |
| Submit MFA(If required) and check for the status |
PUT Refresh/putMFARequestForSite GET Refresh/getMFAResponseForSite |
PUT providerAccounts GET providerAccounts/{providerAccountId} |
|
View Results |
GET /account/summary/all GET /jsonsdk/DataService/getItemSummariesForSite |
GET accounts |
Add/Update Account Process Status
With the legacy requests, you would have used the errorCode and the status field at the mem site account level to display success or error message information to the users.
In case of Yodlee's core API 1.1, following are the two fields that has to be considered for implementation and knowing the data retrieval state:
providerAccount.status and dataset.additionalStatus that are returned in the PUT and POST providerAccounts should be used for the different states that the provider accounts enter into.
| Scenario | Legacy API Implementation Info | Yodlee's Core API (1.1) |
|---|---|---|
| All accounts got aggregated successfully |
memsiteAccount.status = REFRESH_COMPLETED memsiteAccount.errorCode = 0 |
providerAccount.status = SUCCESS |
| One or more accounts aggregated successfully and rest failed. |
memsiteAccount.status = REFRESH_COMPLETED errorCode at item level indicates the reason for the error |
providerAccount.status = PARTIAL_SUCCESS dataset.additionalStatus field in the account and provider account indicates the reason for the error |
| All accounts got failed |
memsiteAccount.status = REFRESH_COMPLETED errorCode at item or mem site account level indicates the reason for the error. |
providerAccount.status = FAILURE dataset.additionalStatus field in the account and provider account indicates the reason for the error. e.g. INCORRECT_CREDENTIALS, UNEXPECTED_SITE_ERROR |
| Account Summary Retrieved | memsiteAccount.status = | dataset.additionalStatus = ACCT_SUMMARY_RECEIVED |
Legacy to Yodlee's Core API Mappings
| Core Service Legacy API | Yodlee's core YSL API | ||
| Method | URL | Method | URL |
| GET | /account/summary/all | GET | accounts |
| POST | /ItemAccountManagement/activateItemAccount | PUT | accounts/{accountId} |
| POST | /authenticate/coblogin | POST | cobrand/login |
| POST | /TransactionCategorizationService/categorizeTransactions | PUT | transactions/{transactionId} |
| POST | /TransactionSearchService/clearUserTransactions | N/A | |
| POST | /ItemAccountManagement/deactivateItemAccount | PUT | accounts/{accountId} |
| POST | /TransactionSearchService/executeUserSearchRequest | GET | transactions |
| POST | /DataService/getItemSummariesWithoutItemData | GET | accounts |
| transactions | |||
| statements | |||
| holdings | |||
| POST | /TransactionCategorizationService/getTransactionCategoryTypes | GET | transactions/categories |
| POST | /TransactionSearchService/getUserTransactions | GET | transactions |
| POST | /TransactionCategorizationService/getUserTransactionCategories | GET | transactions/categories |
| POST | /Login/getUserInfo | GET | user |
| POST | /authenticate/login | POST | user/login |
| POST | /Login/logout | POST | user/logout |
| POST | /UserRegistration/register3 | POST | user/register |
| POST | /UserRegistration/unregister | DELETE | user/unregister |
| POST | /UserRegistration/updateEmail | PUT | user |
| POST | /Login/validateUser | N/A | |
| POST | /TransactionCategorizationService/manageUserCategories | POST | transactions/categories |
| PUT | transactions/categories | ||
| Container based Legacy API | Yodlee's YSL 1.1 API | ||
| Method | URL | Method | URL |
| POST | /addItemForContentService1 | POST | providerAccounts |
| POST | /getItemSummaryForItem1 | GET | accounts/{accountId} |
| POST | /getLoginFormForContentService | GET | providers/{providerId} |
| POST | /getAllContentServices | GET | providers |
| POST | /getContentServiceInfo1 | GET | providers/{providerId} |
| POST | /getContentServicesByContainerType2 | N/A | |
| POST | /getRefreshInfo1 | GET | providerAccounts/{providerAccountId} |
| POST | /getMFAResponse | GET | providerAccounts/{providerAccountId} |
| POST | /isItemRefreshing | N/A | |
| POST | /startRefresh7 | PUT | providerAccounts |
| POST | /stopRefresh | ||
| POST | /putMFARequest | PUT | providerAccounts |
| POST | /removeItem | DELETE | providerAccounts/{providerAccountId} |
| POST | /removeItemAccount | DELETE | accounts/{accountId} |
| POST | /updateCredentialsForItem1 | PUT | providerAccounts |
| Site based service Legacy API | Yodlee's YSL 1.1 API | ||
| Method | URL | Method | URL |
| POST | /SiteAccountManagement/addSiteAccount1 | POST | providerAccounts |
| POST | /SiteAccountManagement/getAllSiteAccounts | GET | providerAccounts |
| POST | /SiteTraversal/getAllSites | GET | providers |
| POST | /DataService/getItemSummariesForSite | GET | providerAccounts |
| accounts | |||
| POST | /Refresh/getMFAResponseForSite | GET | providerAccounts |
| POST | /SiteTraversal/getPopularSites | GET | providers?priority=popular |
| POST | /SiteAccountManagement/getSiteAccounts | GET | providerAccounts |
| POST | /SiteTraversal/getSiteInfo | GET | providers/{providerId} |
| POST | /SiteAccountManagement/getSiteLoginForm | GET | providers/{providerId} |
| POST | /Refresh/getSiteRefreshInfo | GET | providerAccounts/{providerAccountId} |
| POST | /SuggestedSitesManagementService/getSuggestedSites | GET | providers |
| POST | /Refresh/putMFARequestForSite | PUT | providerAccounts |
| POST | /SiteAccountManagement/removeSiteAccount | DELETE | providerAccounts/{providerAccountId} |
| POST | /SiteTraversal/searchSite | GET | providers?name="searchText" |
| POST | /Refresh/startSiteRefresh | PUT | providerAccounts |
| POST | /SiteAccountManagement/updateSiteAccountCredentials | PUT | providerAccounts |
Please refer the different additionalStatus values that are provided at account level and provider account level. Use them per your solution needs and user experience that you want to offer to your end users.
ErrorCode to Dataset.AdditionalStatus Mappings
The YSL 1.1 APIs no longer return an error code. The error status is now provided in the additionalStatus field. This table describes common errors and their causes in the version 1.1 APIs along with next action to be performed.
| ErrorCode | AdditionalStatus | Scenario | Next Action |
|---|---|---|---|
| 407 | ACCOUNT_LOCKED | The account is locked at the provider site. The user has exceeded the maximum number of incorrect login attempts resulting in the account getting locked. | Instruct the user to visit the provider site and take necessary actions to unlock the account. |
| 518,519,520, 522, 573 | ADDL_AUTHENTICATION_REQUIRED | Additional MFA information is needed at the provider site or to download document additional verification is required. | Instruct the user to provide the required additional MFA information or verification. |
| 507 | BETA_SITE_DEV_IN_PROGRESS | The site for which the data is requested is in the development or beta stage. | Instruct the user to try again later or disable the beta sites. |
| 410, 420, 526 | CREDENTIALS_UPDATE_NEEDED | Unable to log in to the provider site due to outdated credentials. The site may be prompting the user to change or verify the credentials. | Instruct the user to visit the provider site and perform the required actions, and invoke the edit account flow to update the credentials in the Yodlee system. |
| 402, 551 | INCORRECT_CREDENTIALS | Unable to log in to the provider site due to incorrect credentials. The credentials that the user has provided are incorrect. | Instruct the user to provide the correct credentials by invoking the edit account flow. |
| 414,422, 423, 570 | DATA_NOT_AVAILABLE | The requested data or document is not available at the provider site. | Instruct the user to check with the respective data provider or provider site. |
| 509, 523, 524 | INVALID_ADDL_INFO_PROVIDED | The user has provided incorrect MFA information or the MFA information provided has expired. | Instruct the user to provide the correct MFA information. |
| 508, 525, 553, 554,555 | REQUEST_TIME_OUT | The request has timed-out due to technical reasons. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 426 | SITE_BLOCKING_ERROR | The Yodlee IP is blocked by the provider site. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 401, 412, 418, 425, 431, 432, 556, 558, 571 | UNEXPECTED_SITE_ERROR | All error indicating issues at the provider site, such as the site is down for maintenance. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 411, 417, 421, 430, 505 | SITE_NOT_SUPPORTED | Indicates that the site does not support the requested data or support is not available to complete the requested action. For example, site not available, document download not supported at the site, etc. | Inform the user about the latest available status. |
| 575 | DATASET_NOT_SUPPORTED | The requested datasets are not supported. | Either get the dataset/attribute enabled or remove the dataset/attribute from the input. |
| 409, 424 | SITE_UNAVAILABLE | The provider site is unavailable due to issues such as the site is down for maintenance. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 400, 403, 404, 408, 413, 419, 517, 557, 601, 708, 709, , 552, 559, 560, 561, 572, 576, 577, 578, 579 | TECH_ERROR | Indicates there is a technical error. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 406, 427, 428, 429, 521 | USER_ACTION_NEEDED_AT_SITE | The errors that require users to take action at the provider site, for example, accept T&C, etc | Instruct the user to visit the provider site and perform the necessary action. |
| 415,416 | SITE_SESSION_INVALIDATED | Indicates if multiple sessions or a session is terminated by the provider site. | Instruct the user to try again later. |
| 574 | ENROLLMENT_REQUIRED_FOR_DATASET | The dataset cannot be retrieved as the user has not enrolled for it. | Instruct the user to enroll for the dataset and then request for it. |
| 504 | DATA_RETRIEVAL_FAILED | Failed to retrieve the data due to unexpected issues. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
| 811 | PARTIAL_DATA_RETRIEVED | Partial data is retrieved for the dataset. | Instruct the user to try again if the mandatory data is missing. If the request fails repeatedly, report the issue to the customer service team. |
| 506 | NEW_AUTHENTICATION_REQUIRED | The site has requested for OAuth authentication. | The OAUTH based authentication sites can be added or updated only using Yodlee FastLink and not Yodlee APIs. Instruct the user to add the account using FastLink. |
| Any other error code | DATA_RETRIEVAL_FAILED | Failed to retrieve the data due to unexpected issues. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the customer service team. |
For more information about the legacy error codes and their semantics in legacy end points, please refer to page https://developer.yodlee.com/Data_Model/Resource_Provider_Account
Account Type Mappings
Due to low data-population rates the following accountType in the legacy API implementation will be provided as OTHER in the Yodlee API account.accountType attribute:
| Container | Account Type ID | Account Type Value |
|---|---|---|
| bank | 9 | 401k |
| bank | 16 | charge |
| bank | 73 | CMA |
| bank | 77 | accountsPayable |
| bank | 78 | accountsReceivable |
| bank | 79 | association |
| bank | 80 | cash |
| bank | 81 | costOfGoodsSold |
| bank | 107 | Commuter |
| loan | 2 | loan |
| creditCard | 22 | card |
| creditCard | 70 | prepaid |
If you have implemented both legacy and Yodlee API, ensure that the legacy API implementation is using the above mapping to display the account types in your application. The consistency of data displayed in the application is assured irrespective of the legacy or Yodlee API implementation.
I18N & Localization
Currency conversionAmounts/Money attributes in requests like accounts, transactions, holdings, etc. are not converted and are given as they are retrieved from the provider site or provided by the user.
Summary amounts in the requests under the derived endpoint are converted to the user’s preferred currency using currency conversion rates.
If the user has no preferred currency set, the summary amounts are converted to cobrand’s preferred currency.
Localization
Localization is performed for the following attributes:
- Transaction Category Names(Master Level Category).
- Provider Attributes – name, URLs, etc.
- If the site is supporting the locale that is derived using the locale preference, the site attributes will be provided in that locale.
- If the site is not supporting the locale that is derived using the locale preference, the site attributes will be provided in the site’s primary locale
- User login locale
- User register locale
- Cobrand login locale
- Cobrand default locale
Handling Newly Introduced Features
Account Types Support ExtendedAccount types support in the Yodlee platform is extended to the following two account types:
- Pension – A pension account is an investment product into which scheme members pay contributions to build up a lump sum to provide an income in retirement.
- Securities backed line of credit (SBLOC) – The SBLOC accounts are popular with large investment firms in the US, where securities are used as collateral to extend a line of credit.
The account deduplication feature prevents storage of duplicate account information in the Yodlee system by checking if the account is already aggregated or is a new account. This ensures only one instance of a user’s account is available in the Yodlee system.
An account will be mapped to one primary providerAccount and the other associated providerAccounts will be in the associatedProviderAccountId attribute of the GET accounts API response.
Re-adding of Accounts
Re-adding accounts with the same set of credentials using Yodlee APIs or Yodlee FastLink should be encouraged only to retrieve deleted accounts. An account should not be re-added to edit the provider accounts’ credentials or to refresh the account to retrieve the latest account information.
Dataset Requesting Capabilities
In Yodlee core API version 1.1, Yodlee has introduced flexibility to mandate the retrieval of existing data attributes that are specifically required for your business flow. As Yodlee incurs additional cost to retrieve the following information from pages other than the landing page, you will have to subscribe for the dataset attributes if they are critical for your business flow:
- Interest Details – The dataset attribute provides details of the interest rate for a student loan accounts under the loan container.
- Payment Details – The dataset attribute consists of loan payment-related details such as payoff amount, outstanding balance, etc. If both the attributes are mandatorily required for your use case then both the attributes have to be explicitly requested.
- Coverage – The dataset attribute provides coverage-related details of superannuation accounts, life insurance, and health insurance under the investment and insurance containers.
REFRESH Webhooks Notifications
Unlike legacy requests, the RESTful Yodlee core API has webhooks support to indicate the customers on the progress of add account, edit account and update account flows. This eliminates the need of polling the requests at frequent intervals. Refer to the developer portal to learn more about webhooks and the implementation details.
Data Extracts Implementation
If the customers are using the legacy Yodlee core API and had implemented synchronized data extracts, your implementation has to be replaced with the RESTful Yodlee core API. Refer to the data extracts page for more information and implementation details.
We also have built the data extracts feature with webhooks notification capability.
PKI Encryption
PKI Encryption allows enhanced secure handling of sensitive data during the Link Account processes. Yodlee recommends that developers use PKI encryption when they migrate to the RESTful Yodlee core API.
Customers have to encrypt the credentials and the answers for their questions before they send the same to Yodlee, if they turn on PKI. If customers use Yodlee FastLink, the PKI encryption will be taken care of by Yodlee. For more details, refer to the Yodlee API with PKI Feature page.
Closed Accounts
With the introduction of Yodlee's core API, Yodlee supports the ability to identify an account as a closed account. The status field of the account entity reflects the state.
Developers can request their users to confirm whether the account is closed when the status is “To be closed”. On receiving user confirmation, POST accounts/{accountId} API has to be invoked to update the account status as closed.
Larger Transaction History
Yodlee provides up to 365 days of a consumer's transaction data when adding an account when the data is available at the financial institution's site. Because fetching all the transaction data takes time, Yodlee has introduced the progressive refresh feature: one large response is broken into multiple small responses whenever required; this is a Yodlee internal process.
Yodlee progressive refresh is helpful in account addition scenarios when the data gathering process fails due to slow financial institution sites or there is a huge volume of consumers’ transaction data. For more details about the feature, refer to the Progressive Refresh for 365 Days of Transaction Data page.
Note: When the progressive refresh feature is enabled, it helps bring 365 days of data during the add account process. The already added accounts will not have an impact and will continue to have the same transaction data that has already been gathered.
New Data AvailabilityFollowing are the new data aggregation capabilities that are available with the Yodlee core API 1.1:
- Documents – Yodlee provides access to end users' financial documents that are generally accessible from financial institution sites such as PDF documents like tax documents, monthly statements, etc.
- User profile information – Data related to the person who is logging into the site and may not always be the actual owner of the accounts. This information will be site specific and directly linked to the account.
- Joint account holder profile information – For joint accounts, the names of individual account owners will be returned (if they are displayed on the site).
- Payment Profile – The payment profile attribute (i.e., available for the student loan account under the loan container) provides details of the payment address of the lender or the loan servicer to which the monthly payment or the payoff amount should be routed to.
- Coverage – The coverage attribute provides coverage-related details of superannuation accounts, life insurance, and health insurance under the investment and insurance containers.
Sample URL Formats
| Legacy API URL Format | Yodlee API URL Format |
|---|---|
|
https://usyirestmaster.yodleeinteractive.com/services/srest/cobrandName… /jsonsdk/DataService/getItemSummariesForSite |
https://usyirestmaster.api.yodlee.com/ysl/accounts |