The connection object is created whenever a user links their financial institution with your app. Connections act as conduits that retrieve account holders' data (i.e. accounts and transactions) from the institution and store it against the User object. Connections can be deleted and recreated so it is recommended that apps access accounts via the User object rather than the connection.

After a connection is successfully established, you can fetch data created after this point by refreshing the connection. This process ensures on-demand data synchronization between your system and Institution itself. Basiq recommends using the Smart Cache to ensure you always have access to the latest data.



Value is "connection".


A string that uniquely identifies the user connection.


User's institution login ID. This value cannot be read. required


User's institution password. This value cannot be read. required


User's institution security code. This value cannot be read. conditional


User's institution secondary login id. This value cannot be read. conditional


Indicates the connection status. Possible values include:

  • pending the connection is in this status briefly until credentials are verified

  • active the connection is valid (is working!) and the credentials have been verified (the jobs steps will continue)

  • invalid the connection is no longer valid and requires the user to update their logon details. Invalid connections cannot refreshed until the password is updated.


UTC Date and Time the connection was created, in RFC 3339 format.


UTC Date and Time the connection was last used, in RFC 3339 format.


Available profile data for the logged in user or data sharer. Where no data is available the attribute is "null". This attribute contains the following properties and will return "null" for data that is unavailable:

  • fullName

  • firstName

  • lastName

  • middleName

  • phoneNumbers - a collection of phone numbers

  • emailAddresses - a collection of email addresses

  • physicalAddresses - a collection of addresses
    - addressLine1
    - addressLine2
    - addressLine3
    - postcode
    - city
    - state
    - country
    - countryCode
    - formattedAddress - full address as a string


The institution the connection relates to.


User's accounts in this institution.


A links object containing the following members:

  • self link to the requested connection

  • accounts link to the accounts associated with this connection

  • transactions link to the transactions associated with this connection


To minimise the exposure of credential details, loginId, password and securityCode are omitted from all server responses.

HTTP/1.1 200 OK
Content-Type: application/json
    "type": "connection",
    "id": "c7231718",
    "status": "active",
    "createdDate": "2020-12-02T02:20:49Z",
    "lastUsed": "2020-12-02T02:20:59Z",
    "profile": {
        "fullName": "Max Wentworth-Smith",
        "firstName": "Max",
        "lastName": "Wentworth-Smith",
        "middleName": "",
        "phoneNumbers": [
            "040534555 ### 991"
        "emailAddresses": [
            "[email protected]"
        "physicalAddresses": [
                "addressLine1": "91 Fisher Road",
                "addressLine2": null,
                "addressLine3": null,
                "postcode": "2099",
                "city": "Dee Why",
                "state": "NSW",
                "country": "Australia",
                "countryCode": "AU",
                "formattedAddress": "13/91 Fisher Rd, Dee Why NSW 2099, Australia"
    "institution": {
        "type": "institution",
        "id": "AU00000",
        "links": {
            "self": ""
    "accounts": {
        "type": "list",
        "data": [
                "type": "account",
                "id": "29a1e18b",
                "accountNo": "2",
                "name": "Transaction 14000",
                "currency": "AUD",
                "class": {
                    "type": "transaction",
                    "product": "Hooli Transaction"
                "balance": "49084.34",
                "availableFunds": "49084.34",
                "lastUpdated": "2020-12-02T02:21:01Z",
                "status": "available",
                "links": {
                    "self": "",
                    "transactions": "'29a1e18b')"
    "links": {
        "self": "",
        "user": "",
        "accounts": "'AU00000')",
        "transactions": "'AU00000')"