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 –

1_new.png 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:

Sample Input: Login form with IAV attributes

	
{
	"loginForm": {
		"row": [{
			"field": [{
				"id": 65499,
				"value": "wewewew"
			}]
		}, {
			"field": [{
				"id": 65500,
				"value": "wewewew"
			}]
		}]
	},
	"include": ["ACCT_PROFILE.FULL_ACCT_NUMBER", "ACCT_PROFILE.BANK_TRANSFER_CODE", "ACCT_PROFILE.HOLDER_NAME"]
}

Sample Input: Field array with IAV attributes

	
{
	"field": [{
		"id": 65499,
		"value": "sathishiav.site16441.5"
	}, {
		"id": 65500,
		"value": "site16441.5"
	}],
	"include": ["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.

 IAV Data Service API Flow