bunq API Anatomy: Monetary Accounts
You’ll encounter different types of accounts once you start integrating with bunq. Some of them are user accounts, some are bank accounts, and some are personal, joint or even shared accounts.
All in all, you’ll find at least 8 names for different accounts you might want your application to interact with:
- User account
- Personal account
- Bank account
- Monetary account
- Business account
- Shared account
- Joint account
- Savings account
The truth is, some of these names may denote one account. Let’s take a closer look at what is what. 🤓
bunq accounts
There are user accounts and monetary accounts. User accounts are the master bunq accounts a user creates when they register at bunq. These accounts can be Personal and Business.
Monetary accounts are money accounts that are linked to the user accounts. They might seem a bit more complex at first glance and so deserve a separate section.
bunq monetary accounts
bunq users can have multiple monetary accounts. They get a default monetary account when they sign up and can then add more monetary accounts of different types. Some of these accounts can be shared with other bunq users. Let’s see how this is reflected in the bunq API.
Level #1: Monetary accounts general
You can get the list of all monetary accounts of a bunq user or read a specific monetary account using the monetary-account resource. In the first case, you’ll need to pass userID, which you can get via GET /user. In the second case, you’ll also have to use itemID, which is the ID of the monetary account.
Trivia: Every object, including monetary-account, monetary-account-joint, user, etc. has an itemID. ItemIDs are simply IDs that do not tell anything about the type of the object.
Here are a couple of examples:
- userID = itemID of the User object
- monetary-accountID = itemID of the MonetaryAccount object
- itemID, as used in the image on the left, is simply the itemID of the Reward object
Level #2: Monetary accounts by type
Bank, Joint, and Savings are all types of bunq monetary accounts. The bunq API lets you create, read, and update all of them. Just as is the case with reading monetary accounts, you’ll need to pass the itemID and/or userID parameters.
Here is an overview of the API resources you need to use to work with different types of monetary accounts.
Bank accounts, both Personal and Business ones, are available via monetary-account-bank. The Business bank accounts can be shared with either full or limited permissions using share-invite-bank-inquiry and share-invite-bank-response.
You can create, read and manage Savings accounts using monetary-account-savings. The resource covers both personal and shared saving accounts.
You can work with Joint accounts by executing one of the monetary-account-joint endpoints. The Connect feature does not work with this type of monetary accounts.
How to recognize the type of monetary accounts
While itemID does not say anything about the type of monetary account, you can still differentiate them when listing monetary-account.
GET /v1/user/{user_id}/monetary-account will return an array of objects. You will find the names there: one by one, they will be labeled either MonetaryAccountBank, MonetaryAccountSavings or MonetaryAccountJoint.
…
How are you using monetary accounts in your integration? Let us know!
