v1.0 to v1.1
The upgrade guide highlights the critical differences between the API versions 1.0 and 1.1 and provides a mapping between both versions and the new features released in version 1.1.
Introducing Yodlee Core API v1.1
Envestnet | Yodlee Core API v1.1, released in January 2018, is the latest version of the flexible RESTful Yodlee core API that has to be integrated along with the FastLink.
Compared to Yodlee API version 1.0 API, Yodlee Core API v1.1 offers the following capabilities through FastLink:
- Ability to retrieve documents during aggregation
- Ability to retrieve PII information during aggregation
- Ability to retrieve 365 days of transactions and verification data in one call
- Simplified status/error information for the add/update account process
Benefits of Yodlee Core API v1.1 include:
- Simplified and faster integration – only a single FastLink integration is needed for multiple data requests and workflows.
- Performance has been improved so only the requested data is retrieved, e.g., choosing transactions under basic aggregation data.
- Reduced user friction and enhanced user experiences.
Use FastLink for Linking Accounts
If you are a customer who has already implemented Yodlee API v1.0, Yodlee strongly recommends you move to FastLink due to the following reasons:
- FastLink has already done the heavy lifting of implementing APIs for account addition and editing credentials. This helps you integrate faster and concentrate more on your business flows.
- With FastLink, you can go faster to market.
- Yodlee has accelerated many experiments to improve the user experience in FastLink that, helps you bring better conversion rates.
- FastLink user experience enhancements reduce user errors to a great extent.
- With the accelerated Open Banking transformation in the US market, there will be frequent changes in the APIs to adapt to the FIs open banking flows; this costs a lot of development time from your side and delays the time to market.
Upgrade Steps
Pre-upgrade
Change the API implementations as per the upgrade guidelines provided on the page. For more information, refer to Yodlee Aggregation API reference v1.1 page. For FastLink, refer to the FastLink 4 Product Guide.
Upgrade Process
Yodlee recommends upgrading using the stage environment before moving to the production environment. Downtime is required for data migration activities.
- Step 1: Data Conversion
Yodlee performs the status code to additional status data conversion. The data migration activity will take 1 hour for a user base of <200K users. - Step 2: Dataset Configuration
Yodlee configures the datasets required for a customer based on their use cases.
Post-upgrade
- Yodlee will restart the customer server so the configurations can take effect. The downtime required varies based on the number of users, the number of accounts, and the number of instances that are available to the customer.
- Once Yodlee notifies you, you can start invoking the FastLink widget.
- To ensure that the calls are a success, test the following scenarios:
- Add accounts for MFA and non-MFA accounts.
- Edit credentials for MFA and non-MFA accounts.
- Instant refresh for MFA and non-MFA accounts.
- Replicate the incorrect credentials and incorrect security answer for Q&A site error scenarios, and rectify the same.
- Monitor the cache refreshes.
Important Notes You Should Know
- Data Not Available Status vs 414/422 Status Codes
The 414 or 422 codes at the account-level in Yodlee API v1.0 indicate the account is not available at the site. In Yodlee Core API v1.1, the DATA_NOT_AVAILABLE indicates the same; this is not an error because it is a site or data unavailability issue. - Fields that Help Display the Refresh and Edit Credentials Options
Before allowing an account or providerAccount to be refreshed, it is essential to make the GET /providerAccount API call to get the latest status of the accounts. Ideally, this call is made when the account display page loads to accurately indicate which accounts can or cannot be refreshed and how they can be fixed.
The updateEligibility field, provided in the GET accounts and GET providerAccounts endpoints, can be used to display the refresh or edit credentials options. The updateEligibility field returns the following values:- ALLOW_UPDATE - Indicates that the user can refresh the account and get the latest data from the financial institution. The account refresh process can be triggered via the API or the FastLink refresh account flow.
- ALLOW_UPDATE_WITH_CREDENTIALS - Indicates that the user will have to take some action on FastLink before the accounts can be updated with the latest data. The FastLink edit flow must be invoked in this case.
Only exception is when additionalStatus is INVALID_ADDL_INFO_PROVIDED or ADDL_AUTHENTICATION_REQUIRED. For these two additionalStatus, use the refresh account flow instead of the edit account flow although the updateEligibility value is set to ALLOW_UPDATE_WITH_CREDENTIALS. - DISALLOW_UPDATE - Indicates that the account data is the latest and cannot be refreshed again at this point. In this case, the user should not be allowed to trigger an account refresh. This value is returned after a successfull aggregation, and stays the same for 15 minutes.
Authentication
- SAML-based Authentication - We do not recommend invoking Yodlee APIs v1.1 using SAML-based authentication. If you are currently using SAML-based authentication, you can continue using SAML only to access FinApps. To access Yodlee API v1.1, refer to the authentication approach on the Aggregation API Reference page. For any other details, contact the Yodlee Client Services team.
- User and Cobrand login-based Authentication - This authentication method is deprecated for Yodlee APIs v1.1. To access Yodlee API v1.1, refer to the authentication approach on the Aggregation API Reference page. For any other details, contact the Yodlee Client Services team.
Data Migration - Status/Error Code Migration
Yodlee Core API v1.0 APIs have refreshInfo.statusCode and a status field to indicate the status of the add/update account process. Multiple status codes are available in the system for similar errors.
To provide a smoother implementation and a better user experience, enhancements have been made so the Yodlee Core API v1.1 can provide meaningful status at the provider account and account-level during the add/update account process. This information is available at the dataset.additionalStatus level.
The accounts that were added using Yodlee Core API v1.0 or FastLink have to undergo the data migration process, which will help provide consistent API responses for the already added provider account and accounts. Yodlee's team will be involved in the data migration process. For details, refer to Status and Error Mapping.
Yodlee Core API v1.0 vs Yodlee Core API v1.1
Unsupported APIs
APIs in v1.0 that have been deprecated and are no longer supported in Yodlee Core API v1.1 follow:
| Endpoint | Service URL |
|---|---|
| accounts | POST accounts/{accountId} |
| provider | GET providers/token POST providers/{providerId} PUT providers/{providerAccountId} |
| providerAccount | GET providerAccount/profile |
| transactions | POST transactions/{transactionId} |
| Refresh | All services under the refresh endpoint are deprecated POST refresh GET refresh GET refresh/{providerAccountId} |
| providers/providerAccount | POST providers/providerAccounts PUT providers/providerAccounts GET providers/providerAccounts GET providers/providerAccounts/{providerAccountId} |
Yodlee’s recommendations for alternative implementations of the deprecated API services are available in the specific API's implementation notes.
For linking accounts and editing credentials flow, Yodlee recommends you use FastLink.
New and Unsupported Fields
Implementation has to be changed as certain fields cannot be returned in the API response. Contact the Yodlee Client Services team if you need assistance. Fields that are no longer supported and their alternatives are as follows:
- Provider API – GET providers and GET providers/{providerId}
Provider API – Unsupported Fields Field Name Description mfaType If MFA information is needed in the add or update processes, the MFA API details are provided in the polling API response or the notification payload. The login form details are identified in the loginFormType field provided in the response. oAuthSite This field has been accommodated in the authType field returned in the provider response and removed.
authType = “OAUTH” indicates that the site is an OAuth site.capability Currently, Yodlee API v1.1 only supports CHALLENGE_DEPOSIT_VERIFICATION capability. The capability filter is available only in the GET providers endpoint and not in GET providers/{providerId}. containerNames Container detail is provided as a child attribute in the dataset attribute. Providing the container name as a separate field is redundant; containerNames has been removed. containerAttributes Container attributes are relevant under the dataset attributes and have been deprecated. additionalDataset The additionalDataset field is provided in the response to indicate whether the sites support verification data like fullAccountNumber, bankTransferCode, and holderName.
In v1.1 API, the same information is provided under the dataset “ACCT_PROFILE”. We have built-in the ability to choose the data to be retrieved so we can maintain consistency in the way data is requested and retrieved.loginHelp The loginHelp under the provider object has been moved under the loginForm object. providerAccountId Support for the providerAccountId filter in the get provider details service has been removed. The core objective of the provider entity is to provide data provider metadata details.
providerAccount endpoint and services have been introduced for the add/update providerAccount implementations.forgetPasswordURL The forgetPasswordURL has been removed from the provider object and has been moved under the login form object.
It makes more sense to include the forgot password URL at the login form where the user’s credentials are accepted.Provider API – New Fields/Fields Name/Data Type/Format Changes Change Type Description Value change for logo field v1.0: The logo value is provided in the PNG format.
v1.1: If the SVG format is available for a provider, it is provided. When the SVG format is not available, PNG will be provided.Value change for favicon field v1.0: The favicon value is provided in the PNG format.
v1.1: If SVG format is available for a provider, it is given. When the SVG format is not available, PNG is provided. - ProviderAccount API – GET providerAccounts and GET providerAccounts/{providerAccountId}
ProviderAccount API – Unsupported Fields Field Name Description refreshInfo The refreshInfo entity has been replaced with dataset entities. Check the status mapping section for details and implementing add/update provider accounts. lastUpdated The lastUpdated field has been removed; the lastUpdated is made available at the dataset level. The lastUpdated field can be found under the dataset entity. ProviderAccount API – New Fields/Fields Name/Data Type/Format Changes Change Type Description Field name change v1.0: lastRefreshAttempt
v1.1: lastUpdateAttempt (This field is made available at the dataset level.)Field name change v1.0: lastRefreshed
v1.1: lastUpdated (This field is made available at the dataset level.)Value change for aggregationSource v1.0:aggregationSource for prepopulated accounts is given as PRE_POPULATED.
v1.1:aggregationSource for prepopulated accounts will be given as SYSTEM.Value change for createdDate v1.0: createdDate was providing a date value.
v1.1: createdDate will provide a date and time value.New field: requestId v1.1: requestId is a unique identifier that is created per Add/Update providerAccount API. New entity: profile v1.1: profile is a new entity that is created under providerAccount and is accessible through the GET verification/holderProfile. Field name change v1.0: nextRefreshScheduled
v1.1: nextUpdateScheduled (This field indicates when the next attempt to update the dataset is scheduled.)
Note: If the next scheduled refresh is not possible for an account, the nextRefreshScheduled attribute is returned for v1.0, and for v1.1 the nextUpdateScheduled attribute will not be returned. - Account API –
Account API – Unsupported Fields Field Name Description refreshInfo The refreshInfo entity has been replaced with dataset entities. Check the status mapping section for details and implementing add/update accounts. Account API – New Fields/Fields Name/Data Type/Format Changes Change Type Description Field name change
v1.0: lastRefreshAttempt
v1.1: lastUpdateAttempt (This field is made available at the dataset level.)Field name change v1.0: lastRefreshed
v1.1: lastUpdated (This field is made available at the dataset level.)Field name change v1.0: holderProfile
v1.1: holder
Note: holder has more PII information compared to holderProfile. Refer to DataModel for details.Value change for createdDate v1.0: createdDate provided a date value.
v1.1: createdDate will provide the date and time value.New field: requestId v1.1: requestId is a unique identifier created from the Add/Update providerAccount API. New field: fullAccountNumberList v1.1: the fullAccountNumberList field provides the full account number retrieved during the ACCT_PROFILE dataset aggregation API.
Note: In v1.0, fullAccountNumber has been deprecated.New entity: profile v1.1: profile is a new entity that is available under providerAccount and is accessible through the GET providerAccount/profile. Field name change v1.0: nextRefreshScheduled
v1.1: nextUpdateScheduled (This field indicates when the next attempt to update the dataset is scheduled.)
Note: If the next scheduled refresh is not possible for an account, the nextRefreshScheduled attribute is returned for v1.0, and for v1.1 the nextUpdateScheduled attribute will not be returned. - Other APIs – Unsupported Fields
Endpoints Entity Field Name Description POST cobrand/config/notifications/events
PUT cobrand/config/notifications/eventsevent
callbackUrl The callback URL support has been made available as a body parameter and the query parameter callbackURL was removed from support. GET transactions transactions category
Support for category filters in the GET transactions and transaction count APIs have been removed as they are redundant and categoryId has been made available. GET holdings holdingType holdingType Support for the holdingType filter in the GET holdings API has been removed. We recommend that you use securityType.
URL and Header Parameter Changes
| Yodlee Core API v1.0 | Yodlee Core API v1.1 |
|---|---|
| API version and cobrandName are part of the URL. | The API version and the customer (cobrand) name are not part of the URL and must be passed as header parameters. The following are the header parameters that must be passed along with the authentication header parameters.
|
The Yodlee Core API v1.1 has to be invoked with the version and the customer (cobrand) name as header parameters. There are API responses for which URLs are provided in the response. For example, pagination URLs in the header, detail links URLs in the body, and URLs in the notification. All URLs provided follow the new format.
Sample URLs follow:
- Yodlee Core API v1.0 – https://usyirestmaster.api.yodlee.com/ysl/{cobrandName}/v1/accounts
- Yodlee Core API v1.1 – https://usyirestmaster.api.yodlee.com/ysl/accounts
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.
Contextual Data in APIs
While linking accounts, editing credentials, or instant refreshing accounts through the FastLink, a requestId (i.e., a unique identifier for a tracking request) is generated and will be returned through post messages or callbacks.
To retrieve contextual-based statuses and data, the requestId should be provided as an input in the GET providerAccounts and GET accounts API call. For example, if a customer is requesting only the ACCT_PROFILE dataset (i.e., verification data), 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 GET accounts or GET providerAccounts 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. |
Data Extracts Implementation
If you had already implemented the data extracts feature, your implementation has to be changed because of changes in v1.1 compared to v1.0. Refer to data extracts for implementation details. The differences in v1.1 compared to v1.0 are as follows:
- Endpoint URL of the get user data and get data extracts event services
- The provider account entity structure in the get user data
- The account entity structure in get user data
- Note that Data Extracts can return a lot of data, and hence by default, pagination is available for the transaction entity in this API. In the first response, the API will retrieve 500 transactions along with other data. The response header will provide a link to retrieve the next set of transactions.
Note: The structure of providerAccount and account is provided in the Aggregation API reference page.
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 provider account 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.
New Capabilities
- Requesting 365 days of transactions and verification data
FastLink version and above has the capability of retrieving 365 days of transactions and verification data like full account number, routing number, and holder details in one flow. This helps customers avoid invoking FastLink twice. - Dataset Requesting Capabilities
In FastLink 4, Yodlee has introduced flexibility to mandate the retrieval of data attributes that are specifically required for your business flow. As Yodlee incurs additional costs to retrieve the following information from pages other than the landing page, you will have to configure the dataset attributes inside the FastLink configuration 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.
- New Data Availability
New data that is available in the Yodlee Core API v1.1 for aggregation compared to Yodlee API v1.0 follows:Capability Endpoint Documents /documents User profile and account holder information
Requesting holder and profile data also brings the secondary account holder information for joint accounts./verification/holderProfile
/accounts?include=holder,profilePayment profile information
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./accounts?include=paymentProfile If you need the above-mentioned datasets, contact the Yodlee Client Services team.
- Flexibility to Configure Auto-refresh
In Yodlee Core API v1.0, auto-refresh was either turned ON or OFF for a customer and no flexibility was available. Yodlee Core API v1.1 offers the option to turn cache-refreshes ON or OFF at the provider account-level and also opt-in for data extracts at the provider account-level.
Known Gaps
The investment options feature that is available in v1.0 APIs is not available in Yodlee Core API v1.1.
Important Notes
- Sensitive Parameters to be Passed as Body Parameters
Envestnet | Yodlee will no longer accept sensitive fields as query parameters for the following v1.0 APIs:- Cobrand Login (POST /{cobrandName}/v1/cobrand/login)
- Register User (POST /{cobrandName}/v1/user/register)
- User Login (POST /{cobrandName}/v1/user/login)
- Update Password (POST /{cobrandName}/v1/user/credentials)
Envestnet | Yodlee’s guidelines and best practices for passing sensitive fields as body parameters for the impacted APIs are available in the implementation notes.
- Security Type
Yodlee recommends customers to use securityType and not holdingType only if securityType is available in the holding API services. Compared to holdingType, securityType is a more normalized value.