Upgrade Guide – 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 flow 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; users provide MFA information just once.

Use FastLink for Linking Accounts

If you are a customer who has already implemented Yodlee API v1.0, Yodlee strongly recommends you to 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 adopt 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 in the page. For more information, refer to Yodlee API v1.1 reference page. For FastLink, refer to the FastLink 3.0 Product Guide and the Getting Started with FastLink pages.

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, 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

  • Error Code vs Status Mapping
    Previously, to detect the success of the aggregation process, you checked statusCode at the account-level. In Yodlee Core API v1.1 you have to check the dataset.additionalStatus at the account-level.
  • 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
    The account.updateEligibility field provided in the GET accounts endpoint can be used to display the refresh or edit credentials options.
    • The refresh or retrieve the latest updates option can be displayed to your users when the value is account.updateEligibility = ALLOW_UPDATE.
    • The edit credentials option can be displayed when the value is account.updateEligibility = ALLOW_UPDATE_WITH_CREDENTIALS.
    Note: When the refresh is not allowed due to incorrect or expired credentials, the ALLOW_UPDATE_WITH_CREDENTIALS option will be provided in the response.

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 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 API Reference page. For any other details, contact the Yodlee Client Services team.
  • API Key-based Authentication - You can continue to use the API key-based authentication to invoke Yodlee APIs v1.1. For more information about this authentication method, click here.

Data Migration - Status/Error Code Migration

Yodlee Core API v1.0 APIs have statusCodes and a status field to indicate the status of the add/update account process and multiple status codes are available in the system for relevant 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. 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.

Dataset Configuration

A dataset is the classification of data that Yodlee retrieves from data providers. To know more about the datasets that Yodlee supports, please refer to Working with Datasets. Depending on the data that you have been retrieving using the 1.0 API and the new data that you need, datasets and the containers have to be configured in the Yodlee back end.

Contact the Sales or the Yodlee Client Services team to configure the datasets and containers you require on-demand, datasets that have to be retrieved by default, and datasets to be configured as auto-refreshable.

Default Dataset Configuration

For your product's primary workflow, if only a fixed set of data is required, it should be configured as implicit or default datasets. Once configured, you do not have to pass the dataset every time you link an account or update an account through FastLink.

If your product requires two different sets of data, you will have to decide which one has to be configured as default. For example, in the aggregation flow, even if no dataset names are passed the default datasets will be considered. But in the account verification flow, you need to explicitly pass datasetName as ACCT_PROFILE to FastLink to retrieve the data related to the dataset. To learn more, refer the FastLink dataset.

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}
providerAccount PUT providers/{providerAccountId}
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 account and edit credentials flow, Yodlee recommends you to 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 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.

  • 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: fullAccountNumber v1.1: the fullAccountNumber field provides the full account number retrieved during the ACCT_PROFILE dataset aggregation API.
    Note: In v1.0, fullAccountNumber has been provided in the accountNumber field.
    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/events

    event

    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 have to be passed as header parameters.
The following are the header parameters that have to be passed along with the authentication header parameters. 
  • Api-version =1.1
  • cobrand-Name={cobrandName}
  • Note: cobrand-Name is not required for the API key-based authentication.

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 URL in the body, and URLs in the notification. All URLs provided follow the new format. 
Sample URLs follow:

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:
  • refreshInfo.status
  • refreshInfo.additionalStatus
  • refreshInfo.statusCode
  • refreshInfo.statusMessage
  • status - Indicates the status of the provider account.
  • dataset.additionalStatus - Indicates the level of success, failure, and in-progress status.

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: The structure of providerAccount and account is provided in the 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.
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

  • 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 3.0 and above versions, Yodlee has introduced flexibility to mandate the retrieval of 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.

  • 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.
    /providerAccount/profile
    /accounts?include=holder,profile
    Payment 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.

Links of Interest