Data Refresh
In this guide, we will walk through how to perform a data refresh.
Our data is updated at regular intervals, but if you require more real-time data, it’s useful to initiate the refresh on your own.
Prerequisites
To be successful, you will first need to authenticate and have a valid Access Token. Take a look at the Authentication Quickstart (Command Line) for a walkthrough of how to authenticate.
After authenticating, you will also need to use the token to access the User ID (this is the sub key) – more documentation about tokens can be found in the Authentication Framework documentation. Worth noting that the Identity Token is seperate from the Access Token.
Requests
We use the /users/{user_id}/fetch
endpoint to trigger the system to start fetching data for a specific user. Once triggered, the system will begin aggregation tasks (essentially updating caches) and will return Task Events until the operation has ended - allowing you to retrieve the aggregated data from different endpoints. The users/{user_id}/fetch
endpoint will return a Task Id that we will use to poll the users/{user_id}/tasks/{task_id}
endpoint for updates to determine when the update task starts and finishes.
PUT /users/{user_id}/fetch
curl -X PUT https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{user_id}/fetch \
-H "Authorization: Bearer {access_token}"
CONSUMER_API_ENVIRONMENT
is specific to your financial institution and matches with Banno Online for your institution.- Example: for the Garden demo institution the
CONSUMER_API_ENVIRONMENT
would be digital.garden-fi.com.
API_VERSION
: API Version (ie. v0)user_id
: The User ID of the user you would like to access data foraccess_token
: Your access token
Response
You will receive a Task ID that will be used for future requests
{
"taskId": "123abc-234def-567ghi-890jkl-1234abcd567"
}
GET /users/{user_id}/tasks/{task_id}
curl https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{user_id}/tasks/{task_id} \
-H "Authorization: Bearer {access_token}"
CONSUMER_API_ENVIRONMENT
is specific to your financial institution and matches with Banno Online for your institution.- Example: for the Garden demo institution the
CONSUMER_API_ENVIRONMENT
would be digital.garden-fi.com.
API_VERSION
: API Version (ie. v0)user_id
: The User ID of the specific user you would like to access data fortask_id
: The Task ID from the previous requestaccess_token
: Your access token
Response
The users/{user_id}/tasks/{task_id}
endpoint will return an array of events starting with TaskStarted. You’ll know that the data refresh has completed if you see a TaskEnded event. If you do not see a TaskEnded event, you’ll need to poll this endpoint on an interval of a few seconds between polls until you see the TaskEnded event.
{
"events": [
{
"date": "2021-01-11T17:17:02.142Z",
"type": "TaskStarted"
},
...
{
"date": "2021-01-11T17:17:04.101Z",
"type": "TaskEnded"
}
],
"version": 10
}
Next Steps
Take a look at specific documentation in the API Reference.
See the Accounts and Transactions guide for how to access the refreshed data.