Upgrade Guide
Upgrade Yodlee API v1.0 to v1.1
The upgrade guide highlights the critical differences between the Yodlee API versions 1.0 and 1.1 with respect to linking accounts, editing credentials, and refreshing accounts. This upgrade guide only applies to customers who build their own link account user experience flows using Yodlee APIs.
Before you go further, we assume that you have already gone through all the steps and differences mentioned in the comprehensive Upgrade Guide - v1.0 to v1.1 page.
Yodlee Core API v1.0 vs Yodlee Core API v1.1
Data Type Changes
In the Yodlee Core API v1.1, the data types for the following fields have been changed:
| API Endpoint | Field Name | Changes |
|---|---|---|
| GET providers/{providerId} | loginForm | v1.0: loginForm is an array of entities. v1.1: loginForm is an array that supports the login form and questions and answers. |
| GET providerAccounts | image | v1.0: the image was providing the value in a byte array format. v1.1: the image will be providing the value in base64 format. |
Add or Update Accounts Status
The statusCode, status, and additionalStatus used for the add or update providerAccount implementation have to be replaced with providerAccount.status and dataset.additionalStatus attributes provided in the webhooks or GET providerAccounts endpoint respectively.
Requesting Aggregation vs Verification Data
In Yodlee Core API v1.0, retrieval of data is limited to predefined fixed aggregation data or verification data during an add/update API. In Yodlee Core API v1.1, it has been made flexible so that customers can request and retrieve only the required data.
| Capability | Yodlee Core API v1.0 Service | Yodlee Core API v1.1 Service |
|---|---|---|
| Basic Aggregation | POST/PUT provider accounts, when invoked with credentials input, retrieve aggregation data like accounts, transactions, holdings, and statements. | POST/PUT provider accounts when invoked with credentials input and dataset details retrieve only those specified in the input. If no dataset information is provided during the request, the default configured datasets will be retrieved. |
| Account Verification | POST/PUT provider accounts, when invoked with additional datasets, retrieve aggregation data like accounts, transactions, fullAccountNumber, routing number, and holder name. | If a customer needs a full account number, holding name, and routing number, the customer should request the ACCT_PROFILE dataset in the input or should be the default configured dataset. |
Note: The add/update account APIs retrieve datasets that are configured by default or demanded during the request.
Contextual Data in APIs
In Yodlee Core API v1.1, the requestId field (i.e., a unique identifier for a tracking request) is generated for every POST providerAccounts or PUT providerAccounts process and is provided in the API response.
To retrieve contextual-based statuses and data, you must provide the requestId as an input in the GET providerAccounts and GET accounts API call. For example, if a customer is requesting only ACCT_PROFILE dataset (i.e., verification data) in the PUT providerAccounts API, the relevant account information data can be retrieved by passing the requestId as an input in the GET accounts API.
The requestId passed should be the one associated with a recent refresh of the account. When requestId is not passed as an input to the API, the responses are not confined to the latest refresh of the account, and the response includes all the data elements associated with the account from its initial aggregation.
Status and Error Mappings
Provider Account Status Mappings
The provider account-level fields that are used to know the progress of the add/update provider accounts and display success or error message to users follow:
| Yodlee Core API v1.0 | Yodlee Core API v1.1 |
|---|---|
Fields that indicate the state, error, and the different status levels of the provider account follow:
|
|
Status Code to Dataset Additional Status Mappings
The following status to additionalStatus mapping will help you to implement the add or update account flows, display error messages, etc., in your application:
| Status Code | Additional Status | 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 locking the account. | 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 because credentials are outdated. 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 then 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 because the credentials are incorrect. 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, 570 | DATA_NOT_AVAILABLE | The requested data or document is not available at the provider site. | Instruct the user to check with the 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 Yodlee Client Services 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 Yodlee Client Services team. |
| 401, 412, 418, 423, 425, 431, 432, 556, 558, 571 | UNEXPECTED_SITE_ERROR | All errors indicating issues at the provider site. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the Yodlee Client Services 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, the site is 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 enable the dataset/attribute or remove the dataset/attribute from the input. |
| 409, 424 | SITE_UNAVAILABLE | The provider site is unavailable. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the Yodlee Client Services team. |
| 400, 403, 404, 408, 413, 419, 517, 552, 557, 559, 561, 572, 576, 577, 578, 579, 601, 708, 709 | TECH_ERROR | It indicates there is a technical error. | Instruct the user to try again later. If the request fails repeatedly, report the issue to the Yodlee Client Services team. |
| 406, 427, 428, 429, 521, 560 | 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 Yodlee Client Services 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 Yodlee Client Services team. |
| 506 | NEW_AUTHENTICATION_REQUIRED | The site requires re-authentication. | Instruct the user to re-authenticate by invoking the edit account flow. |
| 510 | PROPERTY_VALUE_NOT_AVAILABLE | Either the provider site cannot find the property value or the address provided by the user is incorrect. | Instruct the user to provide the correct address or add the real estate account manually. |
| 801, 802 | NA | The 801 and 802 codes are not mapped to any additional status as they are not error codes. They indicate the in-progress state of the add or update account process that is also indicated by providerAccount.status=IN_PROGRESS. | NA |
| 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 Yodlee Client Services team. |
Refresh Webhooks Notifications
In v1.1, the REFRESH webhooks notification payload is different than for v1.0. This is due to the change in the GET providerAccounts response.
Yodlee strongly recommends that customers implement only one version of API. If the customer has implemented both the API versions and has subscribed to the notification, the notifications will always be sent in the latest API version.
If the customer has implemented only the v1.0 version for add or update accounts, the notification will be sent in the 1.0 format.
New Capabilities
Retrieving MFA Questions
Compared to Yodlee API v1.0, the get provider account details service provides the capability to retrieve the MFA questions. While invoking get provider account details include="questions" that have to be passed to retrieve them.
Requesting 365 days of transactions and verification data
Compared to Yodlee API v1.0, the add/update provider accounts have the capability of bringing 365 days of transactions and verification data like full account number, routing number, and holder details in one API call. This helps customers avoid making two API calls one after the other.
Dataset Requesting Capabilities
In Yodlee Core API v1.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 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 mandatory for your use case then both attributes have to be explicitly requested.
Note: If the information is available on the landing page, Yodlee will continue to return the same to you, even if you have not subscribed to the datasets or attributes.
Upgrade Legacy (REST/SOAP) to v1.1
The upgrade guide highlights the critical differences between the legacy API and Yodlee API v1.1 with respect to linking accounts, editing credentials, and refreshing accounts. This upgrade guide only applies to customers who build their own link account user experience using Yodlee APIs.
Before you go further, we assume that you have already gone through all the steps and differences mentioned in the comprehensive Upgrade Guide – Legacy (REST/SOAP) to v1.1 page.
Legacy API vs Yodlee Core API v1.1
The differences between the API calls for each of Yodlee platform capabilities are highlighted in the section.
Linking or Update Accounts
In Yodlee legacy API, the following were the two types of requests used for aggregating data from provider sites:
- Aggregation requests – Retrieves accounts, statements, holdings, and transactions.
- Instant Account Verification (IAV) requests – Retrieves full account number, routing number, and holder details.
In the RESTful Yodlee Core API v1.1, to retrieve aggregation or verification-related information, only one API must be invoked.
Yodlee has classified the aggregation data in the following four datasets:
- BASIC_AGG_DATA
- ADVANCE_AGG_DATA
- ACCOUNT_PROFILE
- DOCUMENTS
| Legacy API Service | Yodlee Core API v1.1 Service |
|---|---|
| Aggregation requests retrieve: accounts, transactions, holdings, and 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, and routing number. | If a customer needs the full account number, holding name and routing number, the customer should request ACCOUNT_PROFILE dataset. |
Note: Customers can also request basic aggregation data and account profile in one request.
Link Account
The API mappings and sequence of API calls in the add account implementation follows:
| Capability | Legacy API Service | Yodlee 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 a query parameter for performing a search. |
| Capture credentials from a user by displaying the site login form. | GET SiteTraversal/getSiteInfo | GET providers/{providerId} |
| Submit Credentials to Yodlee | POST SiteAccountManagement/addSiteAccount1 | POST providerAccounts |
| Check the 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 to webhooks and wait for notifications. For details, refer to the Refresh Webhooks page. |
| Submit MFA (if required) | PUT Refresh/putMFARequestForSite | PUT providerAccounts Note: This step applies to MFA accounts 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 |
Edit Provider or Site Credentials
The API mappings and sequence of API calls in the edit provider or site credentials implementation follows:
| Capability | Legacy API Service | Yodlee Core API v1.1 Service |
|---|---|---|
| Choose a site to edit | GET /account/summary/all GET DataService/getItemSummariesForSite | GET accounts |
| View or retrieve stored credentials | GET SiteTraversal/getSiteloginform | GET providerAccounts/{providerAccountId} Note: The include=credentials parameter should be passed to retrieve the non-password fields that are stored in the system. |
| Submit user-edited credentials to Yodlee | SiteAccountManagement/updateSiteAccountCredentials | PUT providerAccounts |
| Check the 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 get the status of the 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 to webhooks and wait for notifications. For more details, refer to the Refresh Webhooks page. |
| Submit MFA (if required) | PUT Refresh/putMFARequestForSite | PUT providerAccounts |
| Check the 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
The API mappings and sequence of API calls in the update accounts implementation follows:
| Capability | Legacy API Service | Yodlee Core API v1.1 Service |
|---|---|---|
| Choose a site to update | GET /account/summary/all | GET accounts |
| Initiate update | POST Refresh/startSiteRefresh | PUT providerAccounts |
| Check the update account status | GET Refresh/getSiteRefreshInfo | GET providerAccounts/{providerAccountId} |
| Submit MFA (If required) and check 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 |
Legacy to Yodlee Core API v1.1 Mappings
Container-based Legacy API to Yodlee Core API v1.1 Mapping –
Container based Legacy API Yodlee Core API v1.1 Method URL Method URL POST /addItemForContentService1 POST providerAccounts POST /getLoginFormForContentService GET providers/{providerId} POST /getContentServiceInfo1 GET providers/{providerId} POST /startRefresh7 PUT providerAccounts POST /getMFAResponse GET providerAccounts/{providerAccountId} POST /putMFARequest PUT providerAccounts POST /updateCredentialsForItem1 PUT providerAccounts Site-based Service Legacy API to Yodlee Core API v1.1 Mapping –
Site-based Service Legacy API Yodlee Core API v1.1 Method URL Method URL POST /SiteAccountManagement/addSiteAccount1 POST providerAccounts POST /SiteTraversal/getSiteInfo GET providers/{providerId} POST /SiteAccountManagement/getSiteLoginForm GET providers/{providerId} POST /Refresh/putMFARequestForSite PUT providerAccounts POST /Refresh/startSiteRefresh PUT providerAccounts POST /SiteAccountManagement/updateSiteAccountCredentials PUT providerAccounts
Please refer to the different additionalStatus values that are provided at the account-level and provider account-level. Use them as needed go offer the user experience that you want.
Handling Newly Introduced Features
Dataset Requesting Capabilities
In Yodlee Core API v1.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 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 mandatory for your use case then both attributes have to be explicitly requested.
Note: If the information is available in the landing page, Yodlee will continue to return the same to you, even if you have not subscribed to the datasets or attributes.