API Overview

Introduction

Envestnet | Yodlee (“Yodlee”) is a pioneer of financial data aggregation and has continued to innovate while building its enterprise grade data aggregation and analytics platform and APIs for over 17 years. Yodlee regularly works with banks and is periodically examined by U.S. bank regulators. As a result, Yodlee brings its customers the confidence that comes with going to market with a proven, secure technology vendor.

The Yodlee API provides a RESTful API to retrieve aggregated, user permissioned financial data from global financial institutions. Going beyond simple RESTful data pull capabilities, the Yodlee API permits synchronous, asynchronous and event-driven styles of data connectivity and applications. With growing interest in personal and business financial management that is increasingly personalized and instantaneously accessible via the Web and mobile devices, these APIs provide the breadth and depth of data access critical to building modern financial applications. In addition to the API and raw data aggregation and dissemination, Yodlee provides a financial data platform that is configurable to your needs, and performs enhanced data processing, to augment the value of the information that is aggregated. Finally, Yodlee tools such as FastLink, API SDKs and test accounts for financial account simulation accelerate the development process and significantly enhance application resiliency. Collectively, the platform, APIs and tools deliver many benefits that help developers aggregate data from thousands of financial data sites and bring new financial applications to market quickly, and with greater confidence.

Yodlee APIs enable a broad array of use cases that solve a variety of business problems. From personal finance management and account verification for payments processing to credit/lending, wealth management, tax/accounting, and innovative mashups, the types of financial applications you can build with the Yodlee API is limited only by your imagination.

Useful Terminology

Understanding the following terms may be helpful as you read through this API overview and general documentation:

• Customer/Cobrand — A Yodlee customer refers to the business entity that signs the API agreement. Cobrand is a Yodlee internal term referring to a customer API instance on the Yodlee platform. However, the term is generally used in the context of customer credentials associated with the API instance.
• User — A user is the consumer of the application a customer develops using the Yodlee API. A user should be associated with a unique user account through the Yodlee APIs.
• User Account — A user account is an account created by an application with the Yodlee API to refer to a logical entity to which accounts can be linked. A user account should have a 1-1 mapping to a real user of your application. 
• Provider Account vs. Account — A provider account refers to the user’s site account and credentials with a provider (i.e., financial institution website). An account refers to the actual financial account with the institution. For example, a user’s provider account refers to the website access (username/password) a user may have to www.bankofamerica.com, whereas the account refers to the actual checking or savings account he/she may have with Bank of America.

Packaging

You can work with the Yodlee API in one of three ways:

• Sandbox on Developer Portal — Sign up for a developer account on the portal. When you sign up, you get access to an API sandbox and credentials for 45 days that let you call the APIs against real and test accounts. Sandbox access is free for the duration of its validity and is useful for evaluating the APIs. The sandbox provides most capabilities of the Yodlee platform. However, certain advanced capabilities may not be accessible.
• QuickStart — Sign up for the QuickStart service to start using the APIs commercially. It offers access to the most popular financial institutions in your geographical location with a low upfront cost for the first 1000 users. QuickStart offers a low cost, easy way for organizations to get started with the Yodlee API who are in the initial stages of launching an application. QuickStart is available in the U.S., U.K., Australia and South Africa.
• Master Agreement — Once your needs grow beyond what can be supported through QuickStart, you can sign a Master Agreement with us to get full access to all financial institutions and advanced capabilities. Contact sales to create a Master Agreement that meets your needs.

Domain Concepts

Whether you are new to financial data or have been working with it for a while, understanding how Yodlee conceptualizes the domain and structures its data will help you become productive with its APIs. The diagrams that follow highlight the key ideas you should become familiar with.

The first diagram delineates the key domain concepts and hierarchy that Yodlee overlays on the financial data it aggregates. As the diagram below shows, the complexity of the modern financial world results in global financial institutions that conduct business through provider (web)sites that make the corresponding data available to their users.

Each site in turn may have one or more types of services it supports for its users, such as banking, credit, loans and investments.

Yodlee organizes data corresponding to different types of services into containers – a logical construct that roughly denotes collections of site data that generally follow a common ontology (a collection of properties, semantics, and interrelationships) specific to a particular type of financial service. All the containers share some standard information, e.g., account name and account number. However, they differ in types of unshared data. For example, all banking accounts (and bank containers) share the notion of available balance, while the notion of available credit really only makes sense for credit card or loan containers. Each container has a set of properties (some common and some unique) that correspond to the data that corresponds to accounts pertaining to that type of service.

A container in turn can encompass multiple account types that represent variations of the basic financial service that the container captures. For example, bank accounts can be checking or savings accounts. They both share the notion of being bank accounts (and thus correspond to the banking container), but are fundamentally different from a Visa credit card account or a stock brokerage account that correspond to the credit card and investment containers respectively.

Actual customer accounts fall within the scope of a particular type of financial service (and thus correspond to a particular Yodlee container). An account can only belong to one particular container.  Thus, account data that is returned follows the ontology of the container the account type corresponds to. It is important to note that each ontology represents the superset of information that is relevant to a particular service type; every institution is unique in how it defines its services (i.e. may not use/need all properties) or in terms of which data it shares. Thus, not all properties for a particular ontology are applicable, available or returned for all accounts or institutions. The set of data that is actually returned is dynamic and depends on its availability and other factors discussed here.

The following diagram shows an example with various (fictitious) financial institutions that captures these notions.

Beyond these general domain concepts, it is important to become familiar with the type of data that can be returned for accounts. The diagram below outlines how data returned for a particular account (for any account type or container) is structured into datasets. Three types of datasets are aggregated from provider sites. The Derived dataset is produced through platform data processing and adds metadata such as transaction categorization or geolocation. Each dataset is further comprised of a logical grouping of related primitive or composite data elements, which in turn are collections of data property values or actual documents (PDF files, e.g. monthly statements). Although the majority of data properties are aggregated, some of the properties can be obtained through data processing (e.g., transaction category), user input (e.g., real estate value) or system generation (e.g., last refresh timestamp). The Yodlee API supports dataset configuration through the /providers, /providerAccounts and /accounts endpoints to allow retrieval of all or a subset of Basic Aggregation Data, Account Profile and Documents datasets.

The latest version of the Yodlee API allows customization of datasets to retrieve all or a subset of Basic Aggregation Data, Account Profile and Documents. The /providers, /providerAccounts and /accounts endpoints support Dataset configuration. This flexibility provides finer control to selectively pull Datasets based on business needs.

Again, it is important to note, that the diagram represents the universe of content that can possibly be returned. However, not all data applies to or is available for all accounts. For example, E-Bills or Tax information may not be available for a non-interest bearing checking account. The set of data that is actually returned is dynamic and depends on its availability and other factors discussed here.

Scalable and Configurable Aggregation & Data Processing

The Yodlee API and platform are highly configurable. Various flags can be used to control data aggregation and turn platform capabilities on/off. Some aggregation flag examples include the selection of containers for data aggregation, whether or not to download documents, how far back to collect data for (e.g. 30 days vs. 365 days) or whether you would like to retrieve full account numbers (Yodlee Security Office approval required) or only masked account numbers. Platform processing can also be configured to turn on certain premium features like geolocation of merchant transactions. Finally, configuration can be used to control application connectivity options such as whether or not PKI encryption is used for enhanced security or whether to disable FastLink access if APIs are being used to develop a custom account linking capability.  Please contact sales to learn more about the full range of capabilities that can be configured.

In addition to being highly configurable, the aggregation platform and API are scalable and secure. As API call volume grows, the data gathering platform and API back end scales to accommodate the additional workload seamlessly.

Data Model & Data Availability

Yodlee is able to aggregate data from hundreds of account types. In addition to collecting detailed account data elements such as transactions, balances, names, account numbers, etc., the financial data platform is able to aggregate documents pertaining to statements, bills and tax related information. Combined with derived data elements obtained from processing this raw data, the Yodlee API is able to return hundreds of financial data elements that can serve a variety of use cases.

You can learn more about the detailed data model here. The data model pages provide details on the data returned by each of the API endpoints.

To minimize the complexity of modeling hundreds of container/account type variations in both the endpoint structure and data model, the Yodlee API provides singular, generic endpoints for account (/accounts) and transactions (/transactions) rather than a unique endpoint corresponding to each type of account. For example, rather than having separate endpoints for mortgage accounts (e.g., /mortgageAccounts) and checking accounts (e.g., /checkingAccounts), the API simply has an endpoint for accounts (/accounts). The /accounts endpoint returns a collection of accounts. For example, calling GET /accounts may return 2 accounts for a user, 1 checking account (bank container) and 1 mortgage account (loan container). Each account in turn returns data that is relevant and available for only that type of account. For example, a bank account will not return the “interestRateType” field since that field applies only to accounts in a loan container. The documentation however displays all potential fields that can be returned for an account under the account type. The container column in the data model table can help you understand which field can be returned for a particular account based on its container type. You can learn more about which accounts belong to particular containers here. 

In addition to providing a broad spectrum of data elements from hundreds of account types, Yodlee also provides historical reach by being able to aggregate financial data up to 365 days old (depending on availability at site/provider).

When learning to work with aggregated financial data from Yodlee, it is important to keep in mind that not all data listed in the data model is always available. As a practice, null/empty fields are not returned. Some reasons why this might happen include:

• Applicability to Container – Certain fields in the data model may not be returned as they apply to a different container and are not applicable to the type of account for which the data is being returned.
• Account Type Variation – Not all accounts belonging to the same container use all the fields pertinent to that container. For example, maturity dates are applicable only to CD or fixed deposits accounts and not to other account types in a bank container.
• Institution Variation – For the same account type and container, institutions may develop their financial product in different ways; not all fields modeled by Yodlee will be relevant. For example, some checking accounts may be interest bearing while others are not.
• Unavailability at Provider/Site – Not all data elements in the Yodlee data model are always available or accessible from provider sites.
• Unavailability of Derived Data – Not all the derived attributes are applicable for all container or account types. Also, derived data cannot always be computed if there is inadequate information.
• Enabled Features – Certain data is returned only if particular features are turned on; for example, geolocation must be turned on to receive the locations of transactions.

Quick API Tour

The Yodlee API provides comprehensive programmatic access to key capabilities required to build modern FinTech applications. The API endpoints provide access to the following key capabilities:

• Secure Data Access – The /cobrand and /user endpoints primarily address secure data access. Through them, developers can create users that can be associated with provider sites and accounts, authenticate to the API back end, and set up PKI encryption for enhanced security.
• Linking Accounts Through Provider Site Selection and Authentication – To aggregate data from diverse providers, the client application needs to specify the desired provider along with the user access credentials (which constitutes user permission) in order to access financial data in the provider’s (website) account (i.e., “providerAccount” – see below). Yodlee provides APIs to retrieve and work with the provider list, login form fields, and MFA challenges in order to validate data access. This approach to selecting providers, associating access credentials, and validating access for a user is available through the /providers and /providerAccounts endpoints. However, a much simpler and highly recommended approach is to use the FastLink application UI component that can significantly accelerate your time to market as well as hide the complexity of building and testing access to thousands of providers through raw API access. Use the /user/accessTokens endpoint to get a token to launch FastLink.
• Add/Update Account Progress Monitoring – Providing (adding/editing) and validating credentials with provider sites (“Account Linking”) and/or aggregating data (“Refresh”) can take noticeable time.  To be responsive to users, client applications need to know the current status of these activities. Although the Yodlee API has historically supported polling to track the current status of an account linking process (through /providerAccount), it is recommended that client applications now set up webhooks to be notified of certain activities’ progress level or completion. Webhook subscription support is available for “Add Account” and “Edit Account” processes through the /cobrand endpoint. Similar notification support through webhooks is available for monitoring data refresh progress through synchronized data extracts.
• Data Retrieval – The bulk of the API calls your application makes will retrieve different types of data after authentication and account linking. Most of these calls will center on the GET requests for the /accounts, /holdings, /transactions, /statements and /derived endpoints.
• Manual Account and Transaction Input – Certain financial data cannot be aggregated from a financial institution, and must be gathered directly from the user, e.g., value of jewelry or real estate. The Yodlee API allows gathering and managing such manually supplied information through the relevant methods to the /accounts endpoints.
• Categories – The Yodlee API offers robust transaction categorization capabilities. In addition to supporting built-in transaction categorization, the APIs allows applications to manually create/rename/assign/manage transaction categories as well as define and run new rules for transaction categorization. These capabilities are available through the /transactions endpoints.  

Security & Authentication

Given the sensitivity of financial data, access to it through the Yodlee API is highly secure. Secure access practices that you need to be familiar with include:

• All calls to API endpoints must be done over HTTPS and must originate from whitelisted IP addresses.
• API credentialing and authentication requires both customer level and user level (cobrand and user) authentication that must be regularly reaffirmed (see Authentication).
• Access to certain sensitive data (e.g., full account number) requires you to demonstrate that you have a valid use case and the mature capability to handle the data appropriately.
• If you use our APIs to link user accounts (rather than using FastLink) you must use PKI encryption to send user bank site credentials. 

Beyond strong access restrictions, Yodlee invests heavily in platform and data security. You can learn more here.

Building, Testing & Deploying Your Application

Although your application architecture will vary significantly based on your needs, the overall integration approach and architecture of your application with respect to the Yodlee API will be fairly consistent. The diagram below shows a reference architecture for Yodlee API-based applications.

Several things are noteworthy in the diagram above:

• The application front end does not directly invoke Yodlee APIs. For security reasons, only whitelisted IP addresses (usually from your application back end) can invoke the Yodlee API endpoints.
• The application can link user accounts by invoking the relevant APIs. This approach requires the application to handle the secure transmission of user credentials (see the PKI knowledge base article) and manage the complexity of authenticating and handling MFA challenges across arbitrary provider sites. Alternatively, the application can have the front end invoke the FastLink UI component that hides this complexity and provides a customizable look/feel. (FastLink invokes the same APIs behind the scenes.) FastLink can be invoked from Android, iOS, or Web applications.
• The application can receive data by making direct API calls, or choose to receive notifications via webhooks for data that is newly aggregated/available. The application endpoints receiving webhook callbacks need not be whitelisted with Yodlee.
• Data aggregation is Internet facing and firewalled from other platform components. After aggregation, the platform provides critical data processing functionality to ensure the data is clean and has additional metadata so it can be immediately consumed by client applications.  

There are key tasks you must accomplish both in your application code as well as in configuring API access in order to build applications with the Yodlee API.

In code, your application should handle the following key tasks:

• Authenticate to the Yodlee API back end
• Initiate account linking for the user by invoking either the APIs or FastLink. The FastLink approach is recommended as it helps you avoid building and testing complex code for provider authentication and gives you a configurable UI that you can customize for your needs.
• Check on progress of the account linking process, either through polling or event notification via webhooks.
• Retrieve data by invoking the APIs either
  • Immediately on completion of account linking while the user is waiting
  • Later, when a user accesses your application or on a periodic cycle as determined by your application
  • Later depending on availability of new data as determined through polling or event notification through webhooks if you have synchronous data extracts enabled.
• Refresh API cobrand and user session tokens when they expire

Other (optional) setup you might need to do to build an application with the Yodlee API includes:

• FastLink Customization: Customize the look/feel and enabled features in FastLink to match your particular needs. Learn more here.
• API Configuration: Work with your sales team to discuss enabling advanced capabilities through configuration flags. 

If you are a (non-QuickStart) customer who has signed a Master Agreement, Yodlee provides a stage environment for you to build and test your application that is separate from the live production environment. Credentials for both environments are different and can be obtained from your sales contact. For a step-by-step guide to building a simple application with the Yodlee API, try our Getting Started Guide. Also, take a look at our sample app.

Next Steps

If you are interested in evaluating our APIs, you can sign up for a developer account with access to a sandbox environment. Credentials are valid for 45 days and you can work with both live and test accounts.

Alternatively, if you are ready to get started with the Yodlee API but do not want to sign a Master Agreement, you can begin with our standard QuickStart offering. QuickStart will make sense for you if your application has low API volume needs or you are just getting started and want to defer making a deeper commitment and investment until your business scales.

If you are ready to build and deploy a full-scale application and need to learn more, please connect with sales, here.

More Information

As you start using our APIs, make sure you also check out the Data Model, FAQs, Troubleshooting Guide and KnowledgeBase. You can also contact us at YIZen@yodlee.com to help answer questions.