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. It’s worth noting that the Identity Token is separate 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}"

Where:

• 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 for
• access_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}"

Where:

• 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 for
• task_id: The Task ID from the previous request
• access_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.