After following the steps of initiating a bank connection import described in the previous sections, be aware, that there are some processes that happen asynchronously in the background.
Given that the communication to the bank server was successful, the import/update service call returns with various information about the newly created/updated bank connection; in particular, it contains the identifiers of the accounts that have been imported/updated for the connection (attribute
At this point, it is crucial that you regard the
updateStatus attribute of the returned bank connection: this attribute can have two different values:
Bank Connection Update Status IN_PROGRESS
When the import service call returns, you will find that the bank connection's import/update status is usually
IN_PROGRESS. It means that while you can already process the bank connection's data (e.g. the fields about money transfer support) or look up the accounts contained in the
accountIds attribute - the data for the accounts might not be fully downloaded yet. More precisely, ‘data’ here means the account’s balance and transactions/security positions; other data like the account number, account name etc will already be available. But as long as the bank connection’s update status is still
IN_PROGRESS, you might not have any balance information for the accounts, or no (or only a few) transactions/security positions. So we recommend that you either wait until the bank connection's status has switched to
READY or if you want to show account details to the user as fast as possible - let the user know that data download is still in progress in the background.
Bank Connection Update Status READY
Once the bank connection’s status field has switched to
READY, the import/update process is completed.
However, there is another thing that you should be aware of: When the import/update has been completed, it doesn’t necessarily mean that it was successful - in terms of that, all data for all accounts could be successfully loaded. The data for some accounts might have been loaded successfully, while it could have failed for other accounts.
READY just means that there is no ongoing import or update process for this bank connection, and it is ready to be updated again. But to find out the end result of the entire process, you have to now check the status field of the individual accounts (via Get and search all accounts):
UPDATED - means that all data has been successfully downloaded.
DOWNLOAD_FAILED - all or some of its data could not be loaded. For instance, you might have the account's balance, but no transactions. Note that these two statuses are the only statuses that can appear when importing new accounts.
UPDATED_FIXED - only applicable for the update of the bank connection, means that the data could be loaded, however, finAPI detected inconsistencies between the account balance and its transactions. For more details, please see the documentation for this status
DEPRECATED - only applicable for the update of the bank connection, means that the account was no longer sent by the bank server, or could not get matched with an existing account by finAPI. Nothing was changed for this account.
Bank Connection Categorization Status
If you are using Personal Finance Manager (PFM) add-on, aside from the bank connection’s
updateStatus attribute and the accounts' status (
status) attribute, there is another field that might be of interest for you: the bank connection's
categorizationStatus. Similar to the
updateStatus field, as long as the categorizationStatus field is not READY, it means that the process of automatic transactions categorization is still going on. You and your users should be aware that as long as this field is not READY, transactions might still be assigned categories by a background process. More about the categorization and PFM can be found here: Personal Finance Management.
Putting all this information together, here’s a graphic that shows the abstract logic that you should follow in your implementation of the bank connection import/update: