Response Object Details

The purpose of this page is to provide more detail on the fields provided in the responses to API requests.

Institution Object

The institution object represents one institution - most commonly a bank or credit union, but can also be another data provider like Centrelink/myGov.

Property	Example Value	Description
`slug`	cba	The unique reference for this institution. It is a lower case, alphabetic string.
`name`	Commonwealth Bank	The full name of the institution.
`credentials`	-	An array of credentials which are used to log into this institution.
`status`		A text string to describe any current known issues with this institution.
`searchable`	1	A flag to indicate if this institution should be included as a bank for a user to select from. This is only set to zero for institutions which are not banks (eg, Centrelink and myGov).
`display`	1	A flag to indicate if this institution is one of the most popular/common banks, which we display to a user by default. Currently this is a top 10.
`searchVal`	cbathecommonwealthbankofaustraliacommbankcommenwealth	A string of characters which includes a variety of names people may use when referring to this institution, to aid in searching. We remove any non-alphabetic characters from the user’s search value, and do a simple wildcard string match against this field for searching. This occasionally produces funny results, but works very well on the whole. This can also include some common misspellings or typos. ING Direct is one bank where this search method doesn’t work so well - a lot of institutions have ‘ing’ in the name. We treat this as a special case, and if the user has typed exactly ‘ing’, we search instead for ‘ING Direct’.
`region`	au	What country/region this institution belongs to. Currently one of ‘au’, ‘nz’ or ‘uk’, or an empty string for institutions relevant to all regions (eg, the Test institutions).
`export_with_password`	0	Some institutions require the password to be entered again to export data. This flag indicates which those are. This is not relevant for BankFeeds as the API takes care of this complexity automatically.
`estatements_supported`	1	Flag to indicate if we support downloading of officially branded ‘eStatements’ from this institution.
`transaction_listings_supported`	1	Flag to indicate if we support providing transaction listing pdfs for this institution. These are generally screen dumps of the online banking interface, and will have the institution logo on them. Note that this field does not relate to the transaction data which is returned in API responses or on our brand of statement/report.
`card_validation_supported`	0	Flag to indicate if this institution is supported for the CardFlow verification product.
`requires_preload`	0	Flag to indicate that this institution requires a ‘preload’ request. This is generally for institutions where a CAPTCHA image must be loaded and the corresponding text filled in at login. The BankFeeds API combines this with MFA in the ‘Request for Additional Information’ process.
`requires_mfa`	0	Flag to indicate that this institutions requires the use of Multi-Factor Authentication (MFA) for all or most consumer logins. Note that this flag is not actually very useful, as it is possible for almost any institution to use MFA for various individual or groups of customers. In stead of relying on this flag, you should check responses to see if they contain a ‘Request for Additional Information’.
`updated_at`	2016-10-13 10:51:42	DateTime indicating when this institution record was last saved. This field may be updated, even though no changes were actually made to the institution record.
`max_days`	180	The maximum number of days worth of transaction data which we are able to load from this institution.
`get_address_supported`	0	Flag to indicate whether we may be able to load a customer’s address from this institution.

Credential Fields

As mentioned above, each institution has a set of credential fields required for login.

Property	Example Value	Description
`name`	Customer Registration Number	The text label to display to a user to describe this field. These are intended to be consistent with what the user sees when logging in to online banking.
`fieldID`	username	The name of the field to use when submitting a request to the API. This is similar to how a `name` attribute is used in an html form.
`type`	TEXT	The type of this credential, indicating what kind of html input would be appropriate to use. Possible values are TEXT password select captcha
`description`		Used as a brief help text for fields which a user may not be 100% sure of how to fill in, normally optional fields. This is commonly an empty string.
`values`		For credentials of type `select`, this field holds the available values which should be included as options. In JSON, this will be an object, where the keys are the strings to submit with the API requests, and the values are the text to show to the user to make their selection. In xml, the format is either `1 2 3 4` or `Online Security Device Your Passwords`, depending on the types of the keys. We realise that this is by no means an ideal format, and will look to address it in a future version. For non-select types, the value is an empty string.
`defaultKey`	device	The key for the select value which should be set by default in a `select` field.
`keyboardType`	default	This field is used to assist with data entry on mobile especially, where different keyboard types can be displayed based on the type of data to be entered. This can take the following values default number email
`src`		For credentials of type `captcha`, this contains the image source. This will be in data-uri format, suitable for putting directly into the `src` attribute of an `img` tag. This element will not exist for non-captcha field types.
`width`	300	The width attribute for a captcha image. This element only exists for fields of captcha type.
`height`	60	The height attribute for a captcha image. This element only exists for fields of captcha type.
`width`	300	The width attribute for a captcha image. This element only exists for fields of captcha type.

Account Summary

An account summary represents a customer’s single bank account at a single institution at a high level.

Property	Example Value	Description
`accountHolder`	Mr A J Martin	The best account holder name value which we are able to find for this account. No attempt is made to provide these in a consistent format, and these may include joint account holder names, or business names.
`name`	Savings Account 03289	The nickname for the account. Most banks allow the customer to customise this.
`accountNumber`	0032894561	The account number for this account. This should be treated as a string. Where possible we find the ‘external’ account number which can be used from outside the bank. But occasionally only the internal value is available, which may contain letters.
`id`	0032894561	An internal id used for this account. This is not globally unique, but is unique among this customer’s accounts. It may not be consistent across multiple requests.
`bsb`	105-456	The BSB number for this account. This is 6 digits, but may contain spaces or dashes.
`balance`	159.45	The current balance for this account. This will just contain a decimal value, no currency symbol or thousands separator.
`available`	129.85	The current ‘available balance’ for this account.