Before continuing, make sure you have signed-up. When signing up you will need to provide a few details, and confirm your email address - then head on over to the developer dashboard and register your app, and grab an API key.
Now that you have an API key, you can start using the Basiq API to connect to 100s of financial sources!
Although the API is fairly straight forward, there is a little bit of UI work that you need to do on your end to make sure that your users have a seamless and pleasant experience when connecting their bank(s) (financial institution) with your app for the first time.
To help you understand what these steps are, we have prepared the diagram below along with a detailed set of instructions.
Step 1 - Initiate new connection
This is your app. Naturally, your app will be better designed :-) The user initiates the process of connecting their bank by selecting the plus “+” button.
Step 2 - Select bank to connect to
The token should be stored temporarily within your app (e.g. session), as it will be used when making any further API calls to the Basiq service.
Note that the token is temporary and has an expiry period at which point it will no longer work and you will need to re-authenticate your app.
Get list of supported institutions
The app will now call the /institutions endpoint (using the acquired token) to get a list of financial institutions supported by the Basiq API. This list is then presented to the user.
Note that depending on what type of app you are building, you may want to filter the list of institutions that is shown to the user. For e.g. if you are building a personal financial management app, you may want to only list the institutions with a service-type of personal-banking.
The user is finally presented with a list of supported institutions. They select the institution they wish to connect to, and we progress to the next step.
Step 3 - Supply login credentials
In this step we present a form requesting the user to supply their login credentials.
Note that the /institutions/:institutionID endpoint returns a few properties that can help create a better user experience, such as the institution specific labels that should be displayed adjacent to the login and password input fields - for e.g some banks refer to login name as “access id”.
We strongly discourage any of our customers to store the user’s login credentials. We have worked hard to ensure that we provide a secure API service that protects the user's details - so leave as much of the security obligations to us.
The user supplies their credentials, and we continue to the final step.
Step 4 - Create a connection!
The app will now attempt to create a connection via the /connections endpoint. This process may take anywhere from 3 - 15 seconds (depending on the institution being connected to and the network latency).
When a connection is created for the first time, the Basiq API service will authenticate the user using the supplied credentials and if successful will return a list of their accounts along with a unique ID that identifies the newly created connection (called a connectionID).
Your app will need to securely store the connectionID against the user's record (in your local database) - as this id will be used when performing any future connection operations.
Note that the Basiq API intentionally (for security reasons) does not provide any means to retrieve a list of connections that you have created, therefore if you lose the connectionID you will need to create a brand new connection.
In the event that the connection is not successfully created a formatted error response will be returned. Your app should try and handle as many of these as possible. An example could be that the credentials were invalid, in which case you should display the appropriate message to the user and prompt them to re-enter their details.
Getting latest data
When querying the /accounts and /transactions endpoint, the Basiq API will return the cached data that was last obtained from the target institution. This is NOT the latest data, and will most likely not be representative of the user's current account balances and transactions. To obtain the latest data you will need to call the /refresh endpoint. This will force the Basiq API to re-establish the connection with the institution and grab the latest data.
Note that the Basiq API establishes a direct connection with the institution every time the following endpoints are called:
- POST Connections
- PUT Connection
- POST Refresh
Consider caching the institution list
Although we continually onboard new institutions this list doesn’t change that often - so it could be a good idea to cache this list locally and refresh it every so often. This will make your app function a lot faster and avoid having to making an extra API call.