This migration overview highlights the critical differences between the API versions 1.0 and 1.1, and provides mapping between both versions and the new features released in version 1.1.
Introducing Yodlee's core API v1.1
Envestnet | Yodlee 1.1 API is the next version of the flexible RESTful Yodlee core API released in Jan 2018. The APIs provide flexibility in accessing aggregation data through the Envestnet Yodlee aggregation platform.Compared to Yodlee version 1.0 API, Yodlee version 1.1 API have the following capabilities:
- 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
- Contextual add/update account implementation
- Enhanced status/error information for the add/update account process
- Simplified API that help retrieve one or more datasets in one call
- Simplified and faster integration – only a single API 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.
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.
- 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.
Data Migration -- Status/Error Code Migration
In 1.0 there were many status codes at the provider and user account levels and there were instances of more than one error code for similar errors. These similar error codes were helpful to Yodlee teams debugging an issue but were not useful from a developer or user perspective. To provide a smoother implementation and better user experience, enhancements have been made in Yodlee's core API version 1.1 to provide a meaningful status to existing provider accounts and user accounts during the add or update process. Accounts that were added using APIs other than Yodlee's core 1.1 API have to undergo a data migration process. This will help provide consistent API responses for the previously added provider accounts. The Yodlee team will be involved in migrating the data. Attributes like status code and status message fields provided in the provider account of 1.0 API versions have been removed. Newer fields have been introduced in 1.1 API. Customers have to opt for the required dataset configuration. If customers have only one kind of dataset to be retrieved during add and update, we recommend they be configured as default dataset attributes. This avoids providing the datasets and their attributes explicitly while invoking the add and update provider account services.
Configuration of Datasets
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 the Envestnet | Yodlee API Overview v1.1
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.
Please work with the Sales or Customer Care teams to configure datasets and the containers you may need on demand, datasets that have to be retrieved by default, and auto-refreshable datasets.
URL & Header Parameter Changes
| Yodlee core API version 1.0 | Yodlee core API version 1.1 |
|---|---|
| API version and cobrandName are part of the URL. | The API version and the cobrand (customer) 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} |
The version 1.1 API has to be invoked with the version and the cobrand (customer) 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, URLs in notification. All URLs provided follow the newer format.
| Yodlee core API version 1.0 – URL Sample | Yodlee core API version 1.1 – URL Sample |
|---|---|
| https://usyirestmaster.api.yodlee.com/ysl/{cobrandName}/v1/accounts | https://usyirestmaster.api.yodlee.com/ysl/accounts |
Differences between 1.0 & 1.1 Versions
Unsupported APIs
The following APIs that have been deprecated in 1.0 and are no longer supported in 1.1:
| 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} |
Envestnet | Yodlee’s recommendations for alternative implementations of the above deprecated API services are available in the respective API service implementation notes.
Unsupported and New Fields
Certain fields cannot be returned in the API response; you may need to change the implementation. Fields that are no longer supported and the alternatives are explained below. Please contact Yodlee if you need help.
Provider API – Unsupported Fields
Endpoints:
- GET providers
- GET providers/{providerId}
| 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 version 1.1 supports only the aggregation capability; it has been removed from get provider details and get all providers responses. The capability input filter has been removed as well. |
| 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 1.1 API, the same information is provided under dataset “ACCT_PROFILE”. We have built in the ability to choose the data to be retrieved and 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. . It makes more sense to show help with logging in at the login form where the user’s credentials are accepted. |
| 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 end point 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 to be 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
Endpoints:
- GET providers
- GET providers/{providerId}
| ChangeType | Description |
|---|---|
| Value change for logo field | 1.0 version: The logo value is provided in the PNG format. 1.1 version: 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 | 1.0 version: The favicon value is provided in the PNG format. 1.1 version: If SVG format is available for a provider, it is given. When the SVG format is not available, PNG is provided. |
| loginForm | 1.0 version: loginForm is an array of entities. 1.1 version: loginForm is an array that supports the login form and question and answers. |
ProviderAccount API – Unsupported Fields
Endpoints:
- GET providerAccounts
- GET providerAccounts/{providerAccountId}
| 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
Endpoints:
- GET providerAccounts
- GET providerAccounts/{providerAccountId}
| ChangeType | Description |
| Field name change | 1.0 version: lastRefreshAttempt 1.1 version: lastUpdateAttempt (This field is made available at the dataset level.) |
| Field name change | 1.0 version: lastRefreshed 1.1 version: lastUpdated (This field is made available at the dataset level.) |
| Value change for aggregationSource | 1.0 version: aggregationSource for prepopulated accounts is given as PRE_POPULATED. 1.1 version:aggregationSource for prepopulated accounts will be given as SYSTEM. |
| Value change for createdDate | 1.0 version: createdDate was providing a date value. 1.1 version: createdDate will provide a date and time value. |
| Format change for image | 1.0 Version: image was providing the value in byte array format. 1.1 version:: image will be providing the value in base64 format. |
| New field: requestId | 1.1 version: requestId is a unique identifier that is created per Add/Update providerAccount API. |
| New entity: profile | 1.1 version: profile is a new entity that is created under providerAccount and is accessible thru’ GET providerAccount/profile. |
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. |
| associatedProviderAccountId | The associated provider account ids will be available in the 1.0 service response only when the de-duplication feature is turned on and if there is an account that is associated with more than one providers' accounts. The support for this field is not yet built for 1.1 and is planned for a future release. |
Account API - New Fields/Fields Name/Data Type/Format Changes
| Change Type | Description |
|---|---|
|
Field name change |
1.0 version: lastRefreshAttempt 1.1 version: lastUpdateAttempt (This field is made available at the dataset level.) |
| Field name change | 1.0 version: lastRefreshed 1.1 version: lastUpdated (This field is made available at the dataset level.) |
| Field name change | 1.0 version: holderProfile 1.1 version: holder Note: holder has more PII information compared to holderProfile. Refer to DataModel for more details. |
| Value change for createdDate | 1.0 version: createdDate provided a date value. 1.1 Version: createdDate will provide the date and time value. |
| New field: requestId | 1.1 version: requestId is a unique identifier created from the Add/Update providerAccount API. |
| New field: fullAccountNumber | 1.1 version: the fullAccountNumber field provides the full account number retrieved during the ACCT_PROFILE dataset aggregation API. Note: In 1.0 version, fullAccountNumber has been provided in the accountNumber field. |
| New entity: profile | 1.1 version: profile is a new entity that is available under providerAccount and is accessible through GET providerAccount/profile. |
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 get transactions and transaction count have been removed as they are redundant and categoryId has been made available. |
| GET holdings | holdingType | holdingType | Support for the holdingType filter in get holdings has been removed. Our recommendation is that you use securityType. |
Add/Update Accounts
The statusCode, status, and additionalStatus used for the add/update providerAccount implementation have to be replaced with providerAccount.status and dataset.additionalStatus mappings respectively.
Add Flow
Refer to the API flow diagrams for implementing add/update providerAccounts. 
Requesting Aggregation vs Verification Data
In Yodlee's core API 1.0 version, retrieval of data is limited to predefined fixed aggregation data or verification data during an add/update API.
In Yodlee's core API 1.1 version, it has been made flexible so that customers can request and retrieve only the required data.
| Capability | Yodlee core API version 1.0 service | Yodlee core API version 1.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 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: Add/Update Account APIs retrieves datasets that are configured by default or demanded during the request.
Contextual Data API
In Yodlee's core API version 1.1, requestId, a unique identifier gets generated for every add providerAccount or update providerAccount API. This requestId should be used as input in the get provider account detail service to retrieve the contextual based statuses.
Status Mappings
ProviderAccount Status Mappings
While using the version 1.0 API, you would have used the statusCode, status, and additionalStatus fields at the provider account level to know the progress of add/update provider accounts and display success or error message information to users.
| Scenario | Yodlee core API version 1.0 | Yodlee core API version 1.1 |
|---|---|---|
| Login to the provider site is in progress. |
providerAccount.status = IN_PROGRESS
providerAccount.additionalStatus = LOGIN_IN_PROGRESS |
providerAccount.status = LOGIN_IN_PROGRESS |
| User input required to complete the login to the provider. |
providerAccount.status = IN_PROGRESS
providerAccount.additionalStatus = USER_INPUT_REQUIRED |
providerAccount.status = USER_INPUT_REQUIRED |
| Login complete at the provider site. |
providerAccount.status = IN_PROGRESS
providerAccount.additionalStatus = LOGIN_SUCCESS |
providerAccount.status = IN_PROGRESS |
| All accounts were aggregated successfully. | providerAccount.status = SUCCESS | providerAccount.status = SUCCESS |
| One or more accounts were aggregated and others failed. | providerAccount.status = PARTIAL_SUCCESS |
providerAccount.status = PARTIAL_SUCCESS
dataset.additionalStatus field in the account and provider account indicates the reason for the error. |
| All accounts failed | providerAccount.status = FAILED |
providerAccount.status = FAILED
dataset.additionalStatus field in the account and provider account indicate the reason for the error. |
Please refer to the different additionalStatus values that are provided at the account and provider account levels. Use them as needed and for the user experience that you want to offer your users.
StatusCode to Dataset.AdditionalStatus Mappings
| StatusCode | 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. |
Data Extracts Implementation
If you had already implemented the data extracts feature, your implementation has to be changed because of changes in version 1.1 compared to 1.0. Refer to data extractsfor implementation details. The differences in version 1.1 compared to 1.0 version are as follows:- Endpoint URL of Get user data & Get data extracts event services
- provider account entity structure in get user data
- account entity structure in get user data
Note: The structure of providerAccount and account can be seen in the API reference document.
Refresh Webhooks Notifications
In version 1.1, the REFRESH webhooks notification payload is different compared to 1.0. This is due to the change in get provider account response.Yodlee strongly recommends that customers use one version of API. If customers have implementations using both the API versions and if they had subscribed to the notifications, notifications will always be sent in the latest version.
If the customer has implemented only the 1.0 version for add/update accounts, the notification will be sent in the 1.0 format.
New Capabilities
Retrieving MFA Questions
Compared to version 1.0, the get provider account details service provides the capability to retrieve the MFA questions. While invoking get provider account details include="questions" have to be passed to retrieve them.
Requesting 365 days of transactions and verification data
Compared to 1.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 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.
Account Types Support Extended
Yodlee API v1.1 supports the following two account types:
- Pension – A pension account is an investment product in the UK 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.
Following are the new data that are available in the 1.1 version for aggregation compared to 1.0 version.
| Capability | Endpoint |
|---|---|
| Documents | /documents |
|
User profile and account holder information
Requesting holder and profile data brings the secondary account holder information too in case of 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 |
|
Coverage information The coverage attribute provides coverage-related details of superannuation accounts, life insurance, and health insurance under the investment and insurance containers. |
/accounts |
Known Gaps
Following are the features that are available in 1.0 and are not available in 1.1:- Investment options
- Verification service
Yodlee will be building the features listed above in future releases.
Important Notes
Sensitive Parameters to be passed as body parametersEnvestnet | Yodlee will no longer accept sensitive fields as query parameters for the following 1.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 implementation notes.
SecurityTypeYodlee recommends customers make use of only the securityType available in the holding API services and not the holdingType; securityType is a more normalized value compared to holdingType.