William Shakespeare wrote ”a rose by any other name would smell as sweet”, to point out that the name of something can be unconnected to the properties of that thing. But those are fighting words for computer science, where we like names that are closely connected with the properties. We call the software tool that joins your code to libraries, a linker, not a separator or a quibx53. Consulting with a customer recently, I realized that it would help developers to share more widely the definitions of some basic terminology in the Yodlee platform.
If you’re reading this, you are likely a developer and a customer of Yodlee. An older term for our customers is co-brand, because the Yodlee platform can set its visible parts to the customer’s marketing brand. The people who use your fintech app are your customers, and are called end-users or consumers by Yodlee. End-users have a login account with their financial institutions (the financial institution that you login to is also sometimes called a site). The financial institution is a provider (of online accounts). The end-user logs in to their provider. The login account at that institution is a providerAccount. A single providerAccount often gives access to multiple subordinate accounts: checking, saving, loan, credit card, mortgage, etc. These are accounts. Subordinate account is not a Yodlee term.
|customer||Developers using the Yodlee platform||FastPay Apps Inc|
|People using your FinTech app||Mike Smith of 120 Main St, Weston, CT|
|provider, site||Institution hosting an online financial account||Bank of America|
|providerAccount||Online account you log into at the provider (site)||
|account||Any single-purpose account that can be accessed from the providerAccount||Checking account, credit card account, 401K account, loan account, etc|
Let’s consider some terminology relating to development. Like many platform companies, Yodlee provides two different API servers, to separate "code under development" from "code running in production". These two environments are known as ”development” and “production”. Use the development environment for code development and beta testing. When your app is finished, deploy it in the production environment. There’s a third, more-restricted environment, the sandbox, where you can evaluate the Yodlee platform, and make API calls through the Postman tool or our interactive webpage. Overlaid on the three environments is a pricing plan with 4 tiers. You can see the pricing plan here.
The sandbox does not support linking to live (real-world accounts). Instead, use the simulated data and users provided in the sandbox. To test live-linking, enter the Launch pricing tier. Most developers start in the sandbox and spend perhaps a week or two there before upgrading to the development environment to build out and test their app with live data. Developers typically link their own personal accounts to the Yodlee platform, while they are still acquiring real customers.
In every Yodlee environment, users are identified by a unique string referred to as a “login name”. In the sandbox, you are given the login names of five test users. These login names can be seen when you log in to your developer account and look at the dashboard. They are strings with this general appearance “sbMam5e86e0e28c55e1”. You cannot add users in the sandbox. Test user “names” in the sandbox are “test user 1” through “test user 5”. Sandbox test user names represent a real-world name like “Mary Patel” or “Mike Smith”, and, yes, it would probably have been clearer to use real world names instead of strings like “test user 3”.
In Development and Production environments, you assign the unique login names to your customers (end-users). The user loginName can be from 3 to 150 characters, and must not contain any spaces. You, the developer, must create and track unique ids for each of your users. You could use something like a mobile phone number, as long as you cope with telco’s reusing old numbers for new customers. You could use an email address or the actual user id that the consumer uses to login to your app.
Yodlee assigns you, the developer, a unique ID string. You are the admin user for your app on the Yodlee platform, so the unique id for you is known as the "admin user login name". The admin user loginName is used in very few API calls (the few calls which don't process the data of a specific end-user). You can never get account details using your admin user loginName! You always get account details by giving the loginName of the user whose data you want. You pass that loginName to Yodlee when you ask for a CC token. You get back a CC token that encodes the loginName of the end-user. When you pass the CC token in the Authorization HTTP header for subsequent calls, the token tells the Yodlee server which user’s data to work with.
We now have implicit end-user registration in Development and Production environments. If you send a new (not previously seen) user login name to Yodlee, Yodlee will assume this is a new user, and implicitly register the end user. There is an API call you can make later, to add more details (address, phone, etc) to the profile of the new user.
More name definitions
You’ll save time by noting these special Yodlee terms for common data objects.
|container||The container describes the kind of account this is.||Credit card, mortgage, and loan account|
|providerId||A unique identifier for a Financial Institution||Bank of America has providerId 2852|
|providerAccountId||A unique identifier for the combination of provider and providerAccount, created when the user links an account. It is used to track the activities of that link request. This id is fixed until all the accounts held under that providerAccountId are deleted||A number like 10468803|
|accountId||A unique Identifier allocated for each account that we successfully link in the request which is identified by a ProviderAccountId. This value is not the account number that the bank uses. It is a unique id assigned by Yodlee.||A number like 12345678|
You can see the attributes that these objects have by reviewing the Data Model pages. Our data models document the scope of data that may be passed to or returned from API calls. In conclusion, we note that the name-to-object connection was a real buzzkill for the feuding families in Romeo and Juliet. But the name-to-object connections explained here will give you a "rosy" developer experience. Thank you for using the Yodlee platform.