Integration Steps
Step 1- Retrieve Cobrand Session Token
Retrieving cobrand session token is the first step in accessing Yodlee APIs. Every Yodlee API requires a cobrand session token and this is a prerequisite step for accessing all APIs.
API Link – cobrand/login
Sample URL https://stage.api.yodlee.com:443/ysl/sd/v1/cobrand/login
The input parameters for Cobrand Login API (coblogin and cobpassword) for developer portal accounts can be found on the API Dashboard page. Cobrand credentials are different for the staging and production environments.
Notes
- This session is valid for 100 minutes and can be cached and reused for 100 minutes. When the token is about to expire, the API should be invoked again to generate a fresh token.
- All API error codes can be found on this page.
- This session token can be invalidated by using Cobrand Logout API.
Authorization Headers –
To access all other APIs, we need to pass the authorization headers.
Usually, both the Cobrand Session and User Session tokens should be passed as the Authorization Headers but in some cases like the User Register/Login, Get Holdings List, and so on, only the cobrand session token is required.
The screenshot shows how it should be passed in POSTMAN –
The headers are cobSession and userSession.
Step 2- Retrieve User Session Token
Yodlee requires that a new user be created for every user of your application. The main goal is to retrieve the user session token either by registering the new user or logging in the existing user. This User Session Token is required for all APIs that involve retrieving information about the user accounts or linking an account.
Typical Flow – The user provides basic information through your application and when the user is about to link an account with Yodlee, a new Yodlee user should be created in the background. This way the user directly links their provider accounts.
A new user can be created with the register API and a new user session token is generated.
Note – New users cannot be registered on the developer portal. You can only log in using one of the 5 user accounts already created during registration.
The mandatory inputs for registering a new user is shown below. Note that this should be sent as a body parameter.
{
"user": {
"loginName": "ysltestuser1",
"password": "TEST@123",
"email": "yslRest19@yodlee.com"
}
}
If the user is already registered with Yodlee, the User Login API can be used to log in the user and fetch the user session token.
Note – This token expires every 30 minutes. A new session token can be generated and should be cached for 30 minutes. Make sure to pass cobsession Authorization Header as displayed above.
There is no way to retrieve the list of all users registered with Yodlee and hence all usernames and related information must be saved on your side.
The email address of your user is not required by Yodlee. It can be anything and doesn’t need to be unique.
To log out the user after retrieving the accounts and transactions, use User Logout API.
All other user related APIs can be found here.
Step 3- Search Providers
Customers will continue to use the existing GET /v1/providers API to get the list of providers, and if they need providers that support gathering the full account number, bank transfer code, full account holder name, they can pass the filters in the API as input parameters. The API response will return the list of providers that match the filters.
If the customers have routing number handy, they can search for routing number in the ‘name’ input field and get the site they are interested in linking.
API: GET /v1/providers
Input Parameters:
Attribute: addtionalDataSet
Values:
ACCT_PROFILE.FULL_ACCT_NUMBER
ACCT_PROFILE.BANK_TRANSFER_CODE
ACCT_PROFILE.HOLDER_NAME
Sample API Request:
provider?additionalDataSet=ACCT_PROFILE.FULL_ACCT_NUMBER,ACCT_PROFILE.BANK_TRANSFER_CODE,ACCT_PROFILE.HOLDER_NAME
Sample API Response:
{
"provider": [{
"PRIORITY": "SEARCH",
"id": 16441,
"name": "Dag Site",
"loginUrl": "http://64.14.28.129/dag/index.do",
"baseUrl": "http://64.14.28.129/dag/index.do",
"favicon": "https://192.168.210.234:8743/siteImage.bvtmcfast.do?access_type=siteId=16441",
"logo": "https://192.168.210.234:8743/siteImage.bvtmcfast.do?access_type=imageType=LOGO",
"status": "Supported",
"help": "Enter your personal details for registration to authenticate your Bank Credentials",
"oAuthSite": false,
"primaryLanguageISOCode": "EN",
"countryISOCode": "US",
"lastModified": "2013-01-01T18:15:18Z",
"forgetPasswordUrl": "https://accountservices.msn.com/uiresetpw.srf?lc=1033&id=2",
"containerNames": [
"creditCard",
"insurance",
"tax",
"reward",
"bill",
"bank",
"loan",
"investment"
],
"additionalDataset": [{
"name": "ACCT_PROFILE",
"attributes": [{
"name": "FULL_ACCT_NUMBER",
"container": ["BANK"]
}, {
"name": "BANK_TRANSFER_CODE",
"container": ["BANK"]
}, {
"name": "HOLDER_NAME",
"container": ["BANK"]
}]
}]
}]
}
Step 4- Add / Update Account
Once the supported data sets for a provider are confirmed, the POST /v1/providerAccounts API can be called with the relevant supported data sets as needed. This will trigger an add-account request along with an instruction to gather the additional data sets.
APIs:
- POST /v1/providerAccounts
- PUT /v1/providerAccounts
Input Parameters:
Login form / Field array + include=
ACCT_PROFILE.FULL_ACCT_NUMBER
ACCT_PROFILE.BANK_TRANSFER_CODE
ACCT_PROFILE.HOLDER_NAME
Sample API Request:
provider?additionalDataSet=ACCT_PROFILE.FULL_ACCT_NUMBER,ACCT_PROFILE.BANK_TRANSFER_CODE,ACCT_PROFILE.HOLDER_NAME
Sample API Response:
{
"providerAccount": {
"providerId": 123213,
"id": 10487529,
"refreshInfo": {
"status": "IN_PROGRESS",
"additionalStatus": "LOGIN_IN_PROGRESS",
"statusCode": 0,
"statusMessage": "OK",
"lastRefreshed": "2015-06-17T16:46:32Z",
"lastRefreshAttempt": "2015-06-17T16:46:32Z"
}
}
}Step 5- Get Accounts Data
Once the data has been requested in the POST/PUT v1/providerAccounts add/refresh account API calls, and when the gathering process is completed, the data can be retrieved by calling the GET v1/accounts API.
APIs: GET /v1/accounts
Sample Input:
cobrandName: yodlee
accountId: 98144343
status: ACTIVE
Sample API Response:
{
"account": [{
"CONTAINER": "bank",
"providerAccountId": 12345,
"accountName": "SMB account",
"id": 801503,
"holderProfile": [{
"name": {
"displayed": "John Doe"
}
}],
"accountNumber": "23423422344933",
"bankTransferCode": [{
"id": "HDFC0000286",
"type": "IFSC"
}],
"availableBalance": {
"amount": 4699,
"currency": "USD"
},
"accountType": "SAVINGS",
"isAsset": true,
"balance": {
"amount": 84699,
"currency": "USD"
},
"errorCode": 0,
"lastUpdated": "2015-09-20T14:46:23Z",
"providerId": 16441,
"providerName": "Dag Site",
"refreshinfo": {
"errorCode": 0,
"errorMessage": "OK",
"lastRefreshed": "2015-09-20T14:46:23Z",
"lastRefreshAttempt": "2015-09-20T14:46:23Z",
"nextRefreshScheduled": "2015-09-23T14:46:23Z"
},
"accountStatus": "ACTIVE"
}]
}
Appendix
Yodlee APIs are capable of accepting data sets as input parameters as well as able to request data sets based on static configurations. As part of the Search Providers, Yodlee API allows users to search for providers that can return the data sets. Based on the supported data sets for each provider, the add provider API can be called along with the data sets. Yodlee will navigate through the provider site to fetch the requested data sets.
The following are the data sets supported under the category Account Profile –
- Account Profile:
- Full Account Number: Most providers display masked or partial account numbers. Yodlee understands the importance of returning a full account number. It scrapes the full account number wherever possible by doing additional navigation at the site.
- Bank Transfer Code: The bank transfer code is the list of unique ids given to a bank and its branches needed for payment routing purposes. Yodlee is capable of returning the appropriate bank transfer code according to the location of the provider. For U.S. banks, the routing number will be returned and for Indian banks, IFSC will be returned.
- Full Account Holder Name: To verify account ownership, it is critical to have access to the account holder’s full name. With Yodlee APIs, it is possible to get list of sites that support gathering the account holder’s full name as well as requesting and returning the account holder name as part of the link account and refresh account flows.
Yodlee APIs have been modified to request and return enhanced data related to the account profile including full account number, bank transfer code (routing number), full account holder name, and so on.
Note: The enhanced data sets are available only for bank accounts. If an API request is made for the enhanced data sets, a request will be triggered only for bank accounts at the provider site. To trigger data requests for other account types like credit cards, loans, investments and so on, at the provider site, the API call has to be made separately without sending the data requests as input parameters.
Best Practices
- If more than one data set is provided as part of the addtionalDataSet filter in the Search Provider (GET v1/providers) API, then it will use the ‘OR’ operator for the search query. If more than one data set is provided as part of the additionalDataSet filter in the Search Provider (GET v1/providers) API, then the search will provide all the possible results for the datasets supported for the site.
- Read the data sets supported for each provider in the Search Provider (GET v1/providers) API response and then pass the provider id in the Add Account (POST v1/providerAccounts) API.
- Request additional data sets only if really needed as it will have an impact on the latency for fetching the data sets requested.
- If you are an aggregation customer
- You can continue to call the APIs without any changes to the API parameters
- If you are an IAV customer
- You will need to pass at least one of the data sets in the POST/PUT v1/providerAccounts API call. You can select the data sets you need and get the response with these data sets populated when GET v1/accounts is called.
- If you are an aggregation and IAV customer
- If you want to trigger an IAV request, you will need to pass at least one of the data sets in the POST/PUT v1/providerAccounts API call. This will trigger a refresh for bank accounts only. Refreshes will not be triggered for other account types.
- If you want to trigger an aggregation request, you should not pass any of the data sets in the POST/PUT v1/providerAccounts API call. This will trigger a refresh for all the account types supported at the provider level.
- If you trigger a request by passing the data sets in POST/PUT v1/providerAccounts API call for a provider id that doesn’t support these data sets you receive an error message.
FAQs
- Do all banks provide a routing number, full account number, and account holder name?
- Please use the search API to restrict the results to only those banks that return a routing number, full account number, or account holder name.
- How long does it take for me to complete integration with Yodlee IAV?
- It can take anywhere from 2 to 3 weeks with Yodlee FastLink and 4 to 5 weeks without Yodlee FastLink
- Should I require Yodlee FastLink to have users link their accounts?
- Yodlee FastLink is not required and login forms can be built separately. Building login forms could take more time so Yodlee FastLink is recommended.
- How can I delete users’ accounts after linking them with Yodlee?
- Please refer to the Delete API.
- Should I create users with Yodlee?
- For every user of your application, a new user should be created with Yodlee. All activities are then associated with Yodlee and retrieving/deleting accounts is much easier.
- How do I know which provider supports which data sets?
- By calling GET v1/providers with the data sets you need, the API response will display the data sets that are supported and requested.
- How do I get access to these data sets?
- Contact the Yodlee Sales team to enable access to the data sets
- If I am an aggregation customer, will I be able to call the link-account API with data sets?
- No. These data sets are available only with a subscription
- If I am an IAV customer and if I don’t pass any of the data sets in the add-account call, what data will be returned in the response?
- All account level data like account name, partial account number, balances, and so on will be returned. Full account number, bank transfer code, and the account holder’s full name will not be returned.
- How do I trigger a balance refresh call for an account that was already added?
- By calling PUT v1/providerAccounts along with the data sets that you need.
- I don’t intend to use the APIs and build the complex logic of login flows. Do I have an alternative?
- Yes. We recommend you use Yodlee FastLink. Yodlee FastLink is a responsive and flexible developer tool that allows your users to add accounts quickly and easily. It handles complex login forms like multifactor authentication for you. Click here to know more about Yodlee FastLink.
- Can we receive webhook notifications for link/add or update accounts?
- Yes. Webhooks notifications are supported. Please visit the webhooks page for more details.
API Flow
