Accessing Account Data

ℹ️

This guide is intended for developers using Akahu's enduring account connectivity. Information provided may not be relevant for those using one-off account connectivity.

The first thing you are likely to want to do with the Akahu API is retrieve a user's account data. In this guide you will learn how to make an API request to the /accounts endpoint and handle the response.

Prerequisites

Before you can follow this guide, you will need:

• To be able to make a request in your programming language of choice. Our API Reference has example requests using multiple common languages and libraries, just look for the "Language" dropdown at the top of the page.
• A user access token (<<apiKey>>). Follow the Getting Started Guide to obtain one.
• Your app access token (<<appToken>>). You should get this when you create your app.
• An Akahu account with at least one account connected. The user access token must belong to this account.

Making the Request

API Reference

Using your language of choice, make a GET request to the https://api.akahu.io/v1/accounts endpoint, with the following headers:

Authorization: Bearer {{user access token}}
X-Akahu-ID: {{app access token}}

Where the {{user access token}} is replaced with your user access token, and {{app access token}} with your app access token.

Handling Errors

The Akahu API returns standard HTTP response codes.
Below are the most common error codes and their reasons:

• 200 Everything is OK. The response is included in the body.
• 404 The url does not exist. Check you have entered the url correctly.
• 403 You are not allowed to access this resource. Make sure you have a valid user access token with the correct permissions. Also make sure you have set the Authorization header correctly (note the American spelling).

You should treat any response code that is greater than 399 as an error.

Handling the response

The Akahu API uses JSON to encode responses. Most languages have libraries to encode and decode JSON.

The API response will look like:

{
  "success": true,
  "items": [
    {
      "_id": "acc_1111111111111111111111111",
      "connection": {
          "_id": "conn_1111111111111111111111111",
          "name": "Kiwibank",
          "logo": "https://..."
      },
      "name": "My Bank Account",
      "status": "ACTIVE",
      "balance": {
          "available": 1.00,
          "currency": "NZD",
          "current": 1.00,
          "overdrawn": false,
      },
      "attributes": [
          "TRANSACTIONS",
          "TRANSFER_TO",
          "TRANSFER_FROM",
          "PAYMENT_TO",
          "PAYMENT_FROM"
      ],
      "type": "SAVINGS",
      "formatted_account": "01-1234-1234567-12",
      "meta": {
          "holder": "F Bar",
          "address": "10B Imaginary Lane, Auckland, New Zealand"
      },
      "refreshed": {
        "balance": "2021-01-01T12:00:00.000Z",
        "meta": "2021-01-01T12:00:00.000Z",
        "transactions": "2021-01-01T12:00:00.000Z",
        "party": "2021-01-01T12:00:00.000Z"
      },
      "branch": {
          "name": "Your Bank",
          "description": "Your Bank Description",
          "phone": "+64********",
          "address": {
              "postcode": "****",
              "country": "New Zealand",
              "line3": "****",
              "city": "****",
              "line2": "****",
              "line1": "****"
          }
      }
    },
    ...
  ]
}

Lets break this response down a bit:

At the top level, the key success is true. That means that the request was successful.

The items key contains a list of Akahu Accounts, with various information. Don't worry if your account looks a bit different from the one above, different types of accounts have different types of data associated with them. You can read more about what each key means in our Account Model Documentation.

An Account Has a Status of INACTIVE, What Does That Mean?

Akahu currently uses a user's credentials to access their account data. If these credentials ever stop working (eg. if the user changes their password), Akahu updates the status of the account to INACTIVE. An inactive account does not get updated, and will continue to reflect the last active state in which it was seen.

To return the state to ACTIVE, send the user back through the OAuth2 Flow to reconnect their account.

Getting a Single Account

Many apps are centred around one account, rather than all of them. To save you from having to pick that account out of the list every time, you can take that account's _id and update your request url to https://api.akahu.io/v1/accounts/{{_id}}. This will return a similar response, however instead of the items key being a list of accounts, it will return an item key, containing the account specified.

For more details on response formatting, see our reference.

Conclusion

You should now be able to:

• Make a request to the API
• Handle any HTTP errors
• Understand the response format, and retrieve data from it.