Yodlee (Envestnet) Getting Started: Account Setup & First API Call

Getting started overview

Integrating with Yodlee (Envestnet) to access financial data involves a structured process, beginning with developer account creation and culminating in making your first API request. This guide outlines the essential steps to configure your environment and execute a basic data aggregation call. Yodlee provides a sandbox environment specifically for testing integrations without impacting live financial data, which is crucial for development and debugging.

The core of Yodlee's service revolves around its API, which facilitates secure access to a wide range of financial data, including bank accounts, credit cards, investments, and loans. Developers interact with this API using standard HTTP methods and JSON payloads. Authentication typically involves OAuth 2.0, a widely adopted industry standard for delegated authorization, ensuring secure access to user data without sharing user credentials directly with third-party applications. For a general understanding of OAuth 2.0 flows, refer to the OAuth 2.0 specification.

Before making live calls, developers typically work in a sandbox environment that mimics the production API. This allows for testing various API endpoints and data scenarios without real-world financial implications. Yodlee provides comprehensive developer documentation to support this process, including API references, SDK guides, and tutorials.

Getting started quick reference

This table provides a high-level overview of the initial steps to integrate with Yodlee:

Create an account and get keys

To begin using Yodlee's API, you must first create a developer account. This account grants you access to the developer portal, where you can manage your applications, generate API credentials, and access documentation.

1. Register for a Developer Account: Navigate to the Yodlee Developer Portal and sign up for a free Developer Account. This process typically requires providing basic contact information and agreeing to the terms of service.
2. Create an Application: Once logged in, you will need to create a new application within your developer dashboard. This step usually involves giving your application a name and specifying its intended use case. Each application will be associated with a unique set of API credentials.
3. Obtain API Credentials: Upon creating your application, Yodlee will provide you with the necessary credentials:
   • Client ID: A unique identifier for your application.
   • Client Secret: A confidential key used to authenticate your application with Yodlee. Keep this secret secure and do not expose it in client-side code.
   • API Key (Cobrand Name): Often referred to as a Cobrand ID or similar, this identifies your overarching developer entity.

   These keys are crucial for all subsequent API interactions and should be stored securely in your application's configuration or environment variables.

4. Configure Redirect URIs: If your application will use OAuth 2.0 for user authentication (which is typical for Yodlee), you will need to configure redirect URIs in your application settings within the developer portal. These URIs are where Yodlee will redirect the user after they have granted permission to your application. For example, if your application runs locally during development, you might add http://localhost:8080/callback as a redirect URI. Ensure these URIs are correctly specified to prevent authentication failures.

Your first request

After setting up your account and obtaining your API keys, the next step is to make your first API request to confirm your setup is working. This usually involves authenticating and then fetching a list of available financial institutions (providers) or a sample set of accounts in the sandbox environment.

Authentication (OAuth 2.0)

Yodlee uses OAuth 2.0 for authentication. The general flow involves:

1. Client Credential Grant: Your application first authenticates itself to Yodlee using your Client ID and Client Secret to obtain a cobrand session token. This token represents your application's identity.

   POST /auth/token
   Content-Type: application/json
   
   {
     "clientId": "YOUR_CLIENT_ID",
     "secret": "YOUR_CLIENT_SECRET"
   }

   The response will contain the cobrand session token.

2. User Authentication (FastLink): To access user-specific financial data, your application needs to initiate a user session. Yodlee typically provides a hosted solution called FastLink, which is a secure, embeddable UI that guides users through linking their financial accounts. When a user successfully links an account via FastLink, Yodlee provides an access token specific to that user and their linked accounts. Alternatively, you can directly create a user session using an API call if you manage user credentials securely on your end (though FastLink is generally recommended for security and ease of use).

   POST /user/login
   Content-Type: application/json
   
   {
     "loginName": "user123",
     "password": "securepassword"
   }

   This call would return a user session token. Note: In a production scenario, you would integrate FastLink rather than directly handling user credentials.

Making a sample API call: Get Providers

Once you have a valid user session token (or a cobrand session token if you're only accessing cobrand-level data), you can make your first data request. A common first request is to fetch a list of available financial institutions (providers).

Using a tool like cURL or an HTTP client library in your preferred language, construct a GET request to the /providers endpoint. Remember to include your session tokens in the request headers.

curl -X GET \
  'https://sandbox.developer.yodlee.com/ysl/restserver/v1/providers' \
  -H 'Api-Version: 1.1' \
  -H 'Cobrand-Name: YOUR_COBRAND_NAME' \
  -H 'Authorization: Bearer YOUR_COBRAND_SESSION_TOKEN' \
  -H 'User-Session-Token: YOUR_USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json'

Replace YOUR_COBRAND_NAME, YOUR_COBRAND_SESSION_TOKEN, and YOUR_USER_SESSION_TOKEN with your actual credentials. The sandbox URL is https://sandbox.developer.yodlee.com.

Expected Response

A successful response will return a JSON object containing an array of financial providers, each with details such as their ID, name, and supported services. This confirms that your authentication and API call setup are correct.

{
  "provider": [
    {
      "id": 16441,
      "name": "Dagobah Bank",
      "loginUrl": "https://www.dagobahbank.com",
      "status": "ACTIVE",
      "countryIso": "US",
      "isAddedByUser": false
    },
    {
      "id": 17009,
      "name": "Tatooine Credit Union",
      "loginUrl": "https://www.tatooinecu.com",
      "status": "ACTIVE",
      "countryIso": "US",
      "isAddedByUser": false
    }
    // ... more providers
  ]
}

Common next steps

Once you've successfully made your first API call, you can explore more advanced Yodlee features to build out your application:

• Integrate FastLink: For robust user onboarding and account linking, integrate Yodlee's FastLink UI. This simplifies the process for users to connect their financial accounts securely and provides a consistent experience.
• Fetch Accounts and Transactions: Use the /accounts and /transactions endpoints to retrieve detailed financial data for linked users. This is foundational for building personal finance management tools or lending platforms.
• Webhooks for Real-time Updates: Configure Yodlee webhooks to receive real-time notifications about new transactions, account updates, or other important events. This reduces the need for constant polling and improves application responsiveness. For general webhook best practices, consult resources like AWS API Gateway webhook documentation.
• Explore Data Enrichment: Yodlee offers transaction enrichment services that categorize and standardize transaction data, making it more useful for analysis and display within your application.
• SDK Integration: If you are working with a supported language (Java, Python, Ruby, Node.js, PHP, C#), consider using the official Yodlee SDKs to streamline API interactions and handle authentication complexities.
• Error Handling and Logging: Implement robust error handling and logging mechanisms to diagnose issues and ensure the reliability of your integration. Pay attention to Yodlee's specific error codes and messages.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Keys and Tokens: Double-check that your Client ID, Client Secret, Cobrand Name, and session tokens are correct and have not expired. Tokens have a limited lifespan and must be refreshed.
• Verify Endpoint URL: Ensure you are using the correct base URL for the sandbox environment (https://sandbox.developer.yodlee.com/ysl/restserver/v1) and the specific endpoint path (e.g., /providers).
• Headers: Confirm that all required HTTP headers, such as Api-Version, Cobrand-Name, Authorization (with Bearer token), and User-Session-Token, are correctly set. Missing or malformed headers are a frequent cause of errors.
• Content Type: For POST requests, ensure the Content-Type: application/json header is present and your request body is valid JSON.
• Sandbox Data: Remember that the sandbox environment uses simulated data. If you're expecting specific financial institutions or accounts, they might be represented by test data rather than real-world entities.
• Review Error Messages: Yodlee's API typically returns descriptive error messages in JSON format. Carefully read these messages, as they often pinpoint the exact issue. Common errors include 401 Unauthorized (authentication issues) or 400 Bad Request (malformed request).
• Consult Documentation: Refer to the Yodlee Developer Documentation for specific error codes and their resolutions, as well as detailed examples for each API endpoint.
• Firewall/Proxy Issues: If you are making requests from a corporate network, ensure that your firewall or proxy settings are not blocking outbound connections to Yodlee's API endpoints.