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 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 bedigital.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
fetch response { "taskId": "123abc-234def-567ghi-890jkl-1234abcd567" }
GET /users/{user_id}/tasks/{task_id}
curl tasks 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 bedigital.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.
task response { "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.