--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # Get account Get an individual account that the user has connected to your application. > ℹī¸ > > The format for the returned account depends on the permissions you have! For more details see: - [📚 Accessing account data guide](/docs/accessing-account-data) - [📖 Account model](/docs/the-account-model) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Akahu Enduring API", "description": "This API is the primary way for apps to interact with a user's data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.akahu.io/v1" } ], "components": { "parameters": { "xAkahuId": { "name": "X-Akahu-Id", "in": "header", "required": true, "description": "Your **App ID Token**.", "schema": { "type": "string" }, "example": "{{app_token}}" } }, "securitySchemes": { "user_token": { "type": "http", "scheme": "bearer", "description": "User-level Authentication:\n\nHttp Bearer Auth with the token being a consented **User Access Token**.\n> `Bearer {user_token}`\n\nThis will allow you to act on a **user's** behalf when accessing the API." } }, "responses": { "400": { "description": "Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Content-Type" } } } } } }, "401": { "description": "You are not authorised to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Permission Denied" } } } } } }, "403": { "description": "You are not allowed to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "The item you are trying to access doesn't exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not Found" } } } } } }, "500": { "description": "An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" } } } } } } }, "schemas": { "ConnectionId": { "type": "string", "format": "cuid", "pattern": "^conn_[a-z0-9]{25,27}$", "example": "conn_cjgaac5at000001qi2yw8ftil", "description": "The connected financial institution's unique identifier. This will always be prefixed with `conn_`." }, "AccountId": { "type": "string", "format": "cuid", "pattern": "^acc_[a-z0-9]{25,27}$", "example": "acc_c01234567890123456789012345", "description": "A unique identifier for the account in the Akahu system. It is always prefixed by `acc_` so that you can tell that it belongs to an account." }, "AuthorisationId": { "type": "string", "format": "cuid", "pattern": "^authorisation_[a-z0-9]{25,27}$", "example": "authorisation_c01234567890123456789012345", "description": "The authorisation identifier. Financial accounts are connected to Akahu via an authorisation with the user's financial institution. Multiple accounts can be connected during a single authorisation, causing them to have the same authorisation identifier. This identifier can also be used to link a specific account to identity data for the [party](/reference/get_parties) who completed the authorisation." }, "PaymentConsentId": { "type": "string", "format": "cuid", "pattern": "^consent_[a-z0-9]{25,27}$", "example": "consent_c01234567890123456789012345", "description": "A unique identifier for a payment consent. It is always prefixed by `consent_` so that you can tell that it belongs to a payment consent." }, "ConnectionType": { "type": "string", "description": "The type of integration used to connect to this institution.\n\nThis will be one of:\n- `classic` A classic Akahu connection, which uses Akahu's custom built integration to connect to the institution.\n- `official` An official open banking connection, which uses the institution's official open banking APIs.", "enum": [ "classic", "official" ], "example": "official" }, "ConnectionInfo": { "type": "object", "description": "Information about the financial institution where the account is held (eg. ANZ bank).", "properties": { "_id": { "$ref": "#/components/schemas/ConnectionId" }, "name": { "type": "string", "description": "Display name for the connected institution.", "example": "My Bank" }, "logo": { "type": "string", "format": "uri", "description": "A URL pointing to an image of the institution's logo.", "example": "https://cdn.akahu.nz/logos/connections/conn_cjgaac5at000001qi2yw8ftil" }, "connection_type": { "$ref": "#/components/schemas/ConnectionType" } }, "required": [ "_id", "name", "logo", "connection_type" ] }, "PaymentPeriodFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "ANNUALLY" ], "example": "DAILY" }, "PaymentConsentPeriodicLimit": { "type": "object", "description": "The periodic payment limit for a consent, e.g. no more than $50 daily", "properties": { "amount": { "type": "number", "example": 1000 }, "frequency": { "$ref": "#/components/schemas/PaymentPeriodFrequency" } }, "required": [ "amount", "frequency" ] }, "PaymentConsentPayee": { "type": "object", "description": "The payee details for a payment consent", "properties": { "name": { "type": "string", "description": "The holder name of the payee.", "example": "Bilbo Baggins" }, "account_number": { "type": "string", "description": "The account number of the payee, this will be a BECS formatted account number.", "example": "12-1234-1234567-12" } }, "required": [ "name", "account_number" ] }, "AccountPaymentConsent": { "type": "object", "description": "A payment consent for an account, which may be used to initiate payments from that account.", "properties": { "_id": { "$ref": "#/components/schemas/PaymentConsentId" }, "single_limit": { "type": "number", "description": "The single payment limit for this consent, e.g. no more than $1000 per payment.", "example": 1000 }, "periodic_limit": { "$ref": "#/components/schemas/PaymentConsentPeriodicLimit" }, "payees": { "type": "array", "description": "The list of payees that payments using this consent can be sent to, the to account for a payment must match the name and account number exactly.", "items": { "$ref": "#/components/schemas/PaymentConsentPayee" }, "minItems": 1 } }, "required": [ "_id", "single_limit", "periodic_limit", "payees" ] }, "Account": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/AccountId" }, "_migrated": { "type": "string", "format": "cuid", "pattern": "^acc_[a-z0-9]{25,27}$", "example": "acc_c01234567890123456789012344", "description": "The identifier of this account's predecessor.\nThis attribute is only present if the account has been migrated to an official open banking connection from a classic Akahu connection.\n\nRead more [here](/docs/official-open-banking)." }, "_authorisation": { "$ref": "#/components/schemas/AuthorisationId" }, "_credentials": { "type": "string", "deprecated": true, "description": "Deprecated: Please use `_authorisation` instead." }, "connection": { "$ref": "#/components/schemas/ConnectionInfo" }, "name": { "type": "string", "description": "The name of this account. If the connection allows customisation, the name will be the custom name (or nickname), eg. \"Spending Account\". Otherwise Akahu falls back to the product name, eg. \"Super Saver\".", "example": "Demo Account" }, "status": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "INACTIVE" ], "description": "This attribute indicates the status of Akahu's connection to this account.\n\nIt is possible for Akahu to lose the ability to authenticate with a financial institution if the user revokes Akahu's access directly via their institution, or changes their login credentials, which in some cases can cause our long-lived access to be revoked.\n\nThe account `status` will be one of:\n\n- `ACTIVE` Akahu can authenticate with the institution to retrieve data and/or initiate payments for this account.\n\n- `INACTIVE` Akahu no longer has access to this account. Your application will still be able to access Akahu's cached copy of data for this account, but this will no longer be updated by [refreshes](/docs/data-refreshes). Write actions such as payments will no longer be available. Once an account is assigned the `INACTIVE` status, it will stay this way until the user re-establishes the connection. When your application observes an account with a status of `INACTIVE`, the user should be directed back to the Akahu OAuth flow or to https://my.akahu.nz/connections where they will be prompted to re-establish the connection." }, "balance": { "type": "object", "description": "The account balance", "properties": { "currency": { "type": "string", "description": "The (3 letter ISO 4217 currency code)[https://www.xe.com/iso4217.php] that this balance is in.", "example": "NZD" }, "current": { "type": "number", "description": "The current account balance.", "example": 99.9 }, "available": { "type": "number", "description": "The balance that is currently available to the account holder.", "example": 99.9 }, "limit": { "type": "number", "description": "The credit limit for this account. For example a credit card limit or an overdraft limit. This value is only present when provided directly by the connected financial institution.", "example": 1000 }, "overdrawn": { "type": "boolean", "description": "A boolean indicating whether this account is in unarranged overdraft.", "example": false } }, "required": [ "currency", "current" ] }, "type": { "type": "string", "example": "CHECKING", "enum": [ "CHECKING", "SAVINGS", "CREDITCARD", "LOAN", "KIWISAVER", "INVESTMENT", "TERMDEPOSIT", "FOREIGN", "TAX", "REWARDS", "WALLET" ], "description": "Type of account, Akahu provides specific bank account types, and falls back to more general types for other types of connection.\n- `CHECKING` → An everyday spending account.\n- `SAVINGS` → A savings account.\n- `CREDITCARD` → A credit card.\n- `LOAN` → A loan account.\n- `KIWISAVER` → A KiwiSaver investment product.\n- `INVESTMENT` → A general investment product.\n- `TERMDEPOSIT` → A term deposit.\n- `FOREIGN` → An account holding a foreign currency.\n- `TAX` → An account with tax authorities.\n- `REWARDS` → An account for rewards points, e.g. Fly Buys or True Rewards.\n- `WALLET` → Available cash for investment or withdrawal from an investment provider." }, "attributes": { "type": "array", "items": { "type": "string", "example": "PAYMENT_TO", "enum": [ "TRANSACTIONS", "PAYMENT_TO", "PAYMENT_FROM" ] }, "example": [ "TRANSACTIONS", "PAYMENT_TO", "PAYMENT_FROM" ], "description": "The list of attributes indicates which abilities an account has. A list of:\n- `TRANSACTIONS` → account has transactions and supports retrieval of these via Akahu.\n- `PAYMENT_TO` → account can receive payments from any Akahu account with the `PAYMENT_FROM` attribute.\n- `PAYMENT_FROM` → account can initiate payments to any Akahu account with the `PAYMENT_TO` attribute." }, "formatted_account": { "type": "string", "description": "If the account has a well defined account number (eg. a bank account number, or credit card number) this will be defined here with a standard format across connections. Credit cards will have at least 8 digits redacted.", "example": "12-1234-1234567-12" }, "payment_consents": { "type": "array", "description": "A list of authorised payment consents associated with this account.\n\nThis is only present for apps that have been migrated to support the new payment consent model.", "items": { "$ref": "#/components/schemas/AccountPaymentConsent" } }, "meta": { "type": "object", "description": "Metadata regarding this account", "additionalProperties": true, "properties": { "holder": { "type": "string", "description": "The account holder name", "example": "MR DEMO HOLDER & MS DEMO HOLDER" }, "has_unlisted_holders": { "type": "boolean", "description": "Indicates if the account has other holders that are not listed in the holder field. This only applies to official open banking connections where the institution indicates a joint account, but only provides the authorising party's name.", "example": false }, "loan_details": { "type": "object", "description": "Details about a loan account, if available.", "properties": { "purpose": { "type": "string", "description": "The purpose of the loan, if we can't determine the purpose, this will be `UNKNOWN`", "example": "HOME", "enum": [ "HOME", "PERSONAL", "BUSINESS", "UNKNOWN" ] }, "type": { "type": "string", "description": "The type of loan, if we can't determine the type, this will be `UNKNOWN`", "example": "TABLE", "enum": [ "TABLE", "REDUCING", "REVOLVING", "UNKNOWN" ] }, "interest": { "type": "object", "description": "Interest rate information for the loan.", "properties": { "rate": { "type": "number", "description": "The interest rate on the loan.", "example": 4.5 }, "type": { "type": "string", "description": "The type of interest rate.", "example": "FIXED", "enum": [ "FIXED", "FLOATING" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "When this interest rate expires, if available.", "example": "2021-01-01T12:00:00.000Z" } }, "required": [ "rate", "type" ] }, "is_interest_only": { "type": "boolean", "description": "Is the loan currently in an interest only period?", "example": false }, "interest_only_expires_at": { "type": "string", "format": "date-time", "description": "When the interest only period expires, if available.", "example": "2021-01-01T12:00:00.000Z" }, "term": { "type": "object", "description": "The duration/term of the loan for it to be paid to completion from the start date of the loan.", "properties": { "years": { "type": "number", "description": "The number of years the loan is for.", "example": 30 }, "months": { "type": "number", "description": "The number of months the loan is for.", "example": 5 } } }, "matures_at": { "type": "string", "format": "date-time", "description": "When the loan matures, if available.", "example": "2021-01-01T12:00:00.000Z" }, "initial_principal": { "type": "number", "description": "The loan initial principal amount, this was the original amount borrowed.", "example": 100000 }, "repayment": { "type": "object", "description": "Loan repayment information if available.", "properties": { "frequency": { "type": "string", "description": "The frequency of the loan repayment.", "example": "MONTHLY", "enum": [ "WEEKLY", "FORTNIGHTLY", "MONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY" ] }, "next_date": { "type": "string", "format": "date-time", "description": "The next repayment date, if available.", "example": "2021-01-01T12:00:00.000Z" }, "next_amount": { "type": "number", "description": "The next instalment amount.", "example": 1000 } }, "required": [ "next_amount" ] } }, "required": [ "purpose", "type", "interest", "is_interest_only" ] } } }, "refreshed": { "type": "object", "description": "Akahu can refresh different parts of an account's data at different rates. The timestamps in the `refreshed` object tell you when that account data was last updated. This can be thought of as \"Akahu's view of the account (balance/metadata/transactions) is up to date as of \\$TIME\".", "properties": { "balance": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the balance was last retrieved", "example": "2021-01-01T12:00:00.000Z" }, "meta": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when other account metadata was last retrieved (any property apart from balance)", "example": "2021-01-01T12:00:00.000Z" }, "transactions": { "type": "string", "description": "The ISO 8601 timestamp when we last checked for and processed any new transactions. This flag may be missing when an account has first connected, as it takes a few seconds for new transactions to be processed.", "example": "2021-01-01T12:00:00.000Z" }, "party": { "type": "string", "description": "The ISO 8601 timestamp when we last fetched identity data about the party who has authenticated with the financial institution when connecting this account.", "example": "2021-01-01T12:00:00.000Z" } } } }, "required": [ "_id", "_authorisation", "connection", "name", "status", "type", "attributes" ] } } }, "tags": [ { "name": "Accounts" } ], "paths": { "/accounts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An Akahu Account ID", "example": "acc_1111111111111111111111111", "schema": { "type": "string" } } ], "get": { "tags": [ "Accounts" ], "summary": "Get account", "security": [ { "user_token": [] } ], "description": "Get an individual account that the user has connected to your application.\n\n> ℹī¸\n>\n> The format for the returned account depends on the permissions you have!\n\nFor more details see:\n - [📚 Accessing account data guide](/docs/accessing-account-data)\n - [📖 Account model](/docs/the-account-model)", "parameters": [ { "$ref": "#/components/parameters/xAkahuId" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } } } } ```