The institution object represents a financial institution (such as a bank, credit union etc). You can use this object to obtain a list of supported institutions or to get general information about each institution.

📘

Institution Connectors: Stage, Status and Stats

Use attributes stage, status and stats to determine the maturity, availability and performance respectively for each institution connector. Scroll down for more detailed information on both these attributes.

👍

Institution connectors with status = "under-maintenance" - can and should still be used. This status lets you know that they are being continuously improved e.g. improving data enrichment or adding new products, until they mature into stage = "live".

🚧

All connectors with stage = "beta" have the highest possible status = "under-maintenance"

Attributes

type

Value is "institution".

id

A string that uniquely identifies the institution.

name

The full name of the institution.

shortName

Short name of institution.

institutionType

An enum identifying the institution type. Possible values include:

  • Bank

  • Bank (Foreign)

  • Test Bank

  • Credit Union

  • Financial Services

  • Superannuation

country

Country in which this institution operates. English short name used by ISO 3166/MA.

serviceName

Name of the supported service (as defined by the institution).

serviceType

Institution connector: an enum identifying the service type. Possible values include:

  • Personal Banking

  • Business Banking

  • Card Access

  • Test

authorization

Institution connector: an enum identifying the authorization type. Possible values include:

  • user - this means you can create a web connection to this institution, we recommend that you only onboard customers to institutions with this authorization type.

  • user-token - this means you can create a web connection to this institution by passing a user token instead of user credentials [new]

  • other - this means that another authorization method is used for this institution e.g we have a direct API integration which is not publicly available (e.g Regional Australia Bank).

stage

Institution connector: an enum identifying the stage. Possible values include:

  • live - connector is mature

  • beta - connector is complete however is not yet mature

  • new alpha - connector is partially complete

status

Institution connector: an enum identifying the status. Active connectors can continue to be used in every status. Possible values include:

  • operational

  • under-maintenance (all beta connectors are under continuous improvement until they mature into live connectors)

  • degraded-performance

  • partial-outage

  • major-outage

loginIdCaption

Institution connector: caption used by institution to request login id.

secondaryLoginIdCaption

Institution connector: caption used by institution to request secondary login id.

passwordCaption

Institution connector: caption used by institution to request password.

securityCodeCaption

Institution connector: caption used by institution to request security code.

forgottenPasswordUrl

Institution connector: url to forgotten password page

colors

Object that contains institution colours (e.g. primary).

tier

Institution's tier - a representation of it's business and market share in the relevant country/region. Values range from 1 to 4. Tier 1 are Institutions with the highest impact on the market. For example, CBA is a Tier 1 Bank, Suncorp is a Tier 2 Bank, etc.

logo

Object that contains main colors, and URLs of square and full institution logo image, returned in SVG format.

👍

Building UI to select an institution to share data

Many of the attributes on the institutions endpoint relate to institution connectors and enable you to build your own user experience for your customer, such as:

  • loginIdCaption
  • secondaryLoginIdCaption
  • passwordCaption
  • securityCodeCaption
  • forgottenPasswordUrl
  • colors
  • logo

Stats

averageDurationMs

Institution connector statistics are evaluated every 24 hours - to provide average statistics for Jobs occurring in the previous 7 days in milliseconds. Stats are provided for for each job step plus the total.

  • verifyCredentials

  • retrieveAccounts

  • retrieveTransactions

  • retrieveMeta

  • total

📘

Supported Features (all data sources)

Use these attributes to determine which Features are supported for each institution and data source:
web - denotes all data shared via institution connectors
pdf - denotes data uploaded via official pdf bank statements
csv - denotes data uploaded via csv statements

Example 1: "accountNo": ["web", "pdf", "csv"] indicates that the Accounts.accountNo attribute is available for this institution - for data sourced from web, pdf and csv

Example 2: "accountNo": ["pdf"] indicates that the accountNo attribute is available for this institution - only for data sourced from pdf statements

Features

login

Bank authentication or verify credentials step is supported for this institution connector

accounts

Describes the support of Accounts attributes by institution for each data source

  • accountNo

  • name

  • currency

  • balance

  • availableFunds

  • lastUpdated

  • accountHolder

  • meta - mortgage meta data

transactions

Describes the support of Transactions attributes by institution for each data source

  • description

  • date

  • amount

  • balance

  • class

profile

Describes the support of Connection with profile data attributes by institution for each data source

  • firstName

  • lastName

  • middleName

  • emailAddresses

  • physicalAddresses

Links

links

A links object containing the following members:

  • self link to the requested institution

🚧

Institution Connector Stage - alpha, beta or live

When we release a new connector it is initially released as alpha or beta version. The more data we see the more mature the connector becomes until it is upgraded to live. Below are some high level guidelines to indicate what you can expect during each stage.

  • live - connector is mature
  • beta - connector is complete however is not yet mature
  • new alpha - connector is partially complete (use features attribute to determine which data points are supported)

📘

Institution Connector Stage: live connector

This is a mature connector, where we have seen a great variety of account types and transaction data in order to confidently create the right patterns to enable excellent coverage for expense categorisation, and insights for Affordability. For a live connector you can expect the following:

  • comprehensive list of verified product name to account type mappings
  • support for most account types with emphasis on savings, transactions, credit card and mortgage
  • account holder, account class and type (comprehensive support of product name and account type mappings)
  • mortgage meta data where available
  • transaction direction (debit/credit) and class (payment, bank-fee etc)
  • transaction sub-class for payments (enrichment of payments)
  • transaction intervals (for bank statements)
  • connection profile data
  • institution works with affordability solution for income and expenses
  • comprehensive monitoring

📘

Institution Connector Stage: beta connector

This is a very new connector. We leave the connector in this Stage until we have enough variety and coverage of data to upgrade the connector. This is an iterative process and we love partnering with Fintechs to improve our connectors. For a beta connector you can expect the following:

  • verification of credentials for login
  • account class and type (limited support for product name to account type mappings)
  • account and transaction data for savings and transaction accounts to start
  • account status, account number, account balance, available funds for above account types
  • transaction status, amount, balance, description, postdate
  • monitoring of test accounts

📘

Institution Connector Stage: alpha connector

This is a partially complete connector. Use the features attributes to determine what is supported with these connectors. Fintechs keen to help move these alpha connectors to beta stage can use these connectors as the more data the platform retrieves the quicker the connector can mature.

🚧

Institution Connector Status

The Status of institution connectors is evaluated and updated every 30 minutes using jobs occurring in the previous hour.

Where Stage is beta for institution connectors, they will have Status as under-maintenance until they are matured into live institution connectors.

🚧

Institution Connector Stats

The Stats of institution connectors is evaluated every 24 hours using jobs occurring in the previous 7 days to provide an indication of average performance.

{
  "type": "list",
  "totalCount": 56,
  "data": [
    {
      "type": "institution",
      "id": "AU00000",
      "name": "Hooli Bank",
      "shortName": "Hooli",
      "institutionType": "Test Bank",
      "country": "Australia",
      "serviceName": "Personal Online Banking",
      "serviceType": "Personal Banking",
      "loginIdCaption": "Login",
      "passwordCaption": "Password",
      "tier": "4",
      "authorization": "user",
      "features": {
        "login":[
           "web"
         ],
        "accounts": {
          "accountNo": [
            "web"
          ],
          "name": [
            "web"
          ],
          "currency": [
            "web"
          ],
          "balance": [
            "web"
          ],
          "availableFunds": [
            "web"
          ],
          "lastUpdated": [
            "web"
          ],
          "accountHolder": [
            "web"
          ],
          "meta": [
            "web"
          ]
        },
        "transactions": {
          "status": [
            "web"
          ],
          "description": [
            "web"
          ],
          "date": [
            "web"
          ],
          "amount": [
            "web"
          ],
          "balance": [
            "web"
          ],
          "class": [
            "web"
          ]
        },
        "profile": {
          "fullName": [
            "web"
          ],
          "firstName": [
            "web"
          ],
          "lastName": [
            "web"
          ],
          "middleName": [
            
          ],
          "phoneNumbers": [
            "web"
          ],
          "emailAddresses": [
            "web"
          ],
          "physicalAddresses": [
            "web"
          ]
        }
      },
      "forgottenPasswordUrl": "https://hooli.com.au/forgotten...",
      "stage": "beta",
      "status": "under-maintenance",
      "stats": {
        "averageDurationMs": {
          "verifyCredentials": 3600,
          "retrieveAccounts": 4500,
          "retrieveTransactions": 2300,
          "retrieveMeta": 1200,
          "total": 11600
        }
      },
      "logo": {
        "type": "image",
        "colors": null,
        "links": {
          "square": "https://d388vpyfrt4zrj.cloudfront.net/AU00000.svg",
          "full": "https://d388vpyfrt4zrj.cloudfront.net/AU00000-full.svg"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/institutions/AU00000"
      }
    },
    {
      "type": "institution",
      "id": "AU01001",
      "name": "National Australia Bank Limited*",
      "shortName": "NAB",
      "institutionType": "Bank",
      "country": "Australia",
      "serviceName": "NAB Connect",
      "serviceType": "Personal Banking",
      "loginIdCaption": "NAB ID",
      "passwordCaption": "Password",
      "tier": "1",
      "authorization": "user",
      "features": {
        "login":[
           "web"
         ],
        "accounts": {
          "accountNo": [
            "web",
            "pdf",
            "csv"
          ],
          "name": [
            "web",
            "pdf",
            "csv"
          ],
          "currency": [
            "web",
            "pdf",
            "csv"
          ],
          "balance": [
            "web",
            "pdf",
            "csv"
          ],
          "availableFunds": [
            "web",
            "pdf",
            "csv"
          ],
          "lastUpdated": [
            "web",
            "pdf",
            "csv"
          ],
          "accountHolder": [
            "pdf",
            "csv"
          ],
          "meta": [
            "web",
            "pdf"
          ]
        },
        "transactions": {
          "status": [
            "web",
            "pdf",
            "csv"
          ],
          "description": [
            "web",
            "pdf",
            "csv"
          ],
          "date": [
            "web",
            "pdf",
            "csv"
          ],
          "amount": [
            "web",
            "pdf",
            "csv"
          ],
          "balance": [
            "web",
            "pdf",
            "csv"
          ],
          "class": [
            "web",
            "pdf",
            "csv"
          ]
        },
        "profile": {
          "fullName": [
            "web"
          ],
          "firstName": [
            "web"
          ],
          "lastName": [
            "web"
          ],
          "middleName": [
            
          ],
          "phoneNumbers": [
            "web"
          ],
          "emailAddresses": [
            "web"
          ],
          "physicalAddresses": [
            "web",
            "pdf"
          ]
        }
      },
      "forgottenPasswordUrl": "https://www2.my.commbank.com.au...",
      "stage": "live",
      "status": "operational",
      "stats": {
        "averageDurationMs": {
          "verifyCredentials": 3600,
          "retrieveAccounts": 4500,
          "retrieveTransactions": 2300,
          "retrieveMeta": 1200,
          "total": 11600
        }
      },
      "logo": {
        "type": "image",
        "colors": null,
        "links": {
          "square": "https://d388vpyfrt4zrj.cloudfront.net/AU01001.svg",
          "full": "https://d388vpyfrt4zrj.cloudfront.net/AU01001-full.svg"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/institutions/AU01001"
      }
    }
  ]
}