{"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}}"},"ContentType":{"name":"Content-Type","in":"header","schema":{"type":"string"},"example":"application/json"}},"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."},"app_auth":{"type":"http","scheme":"basic","description":"App-level Authentication:\n\nHTTP Basic Auth with the username being your **App ID Token** and the password being your **App Secret**.\n> `Basic {app_token}:{app_secret}`\n\nThis will allow you to act as your Akahu **application**, rather than as a specific user."}},"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"}}}}}},"429":{"description":"You have been rate limited on this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Rate limit exceeded"}}}}}},"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_`."},"IdentityRequestId":{"type":"string","format":"cuid","pattern":"^id_[a-z0-9]{25,27}$","example":"id_c01234567890123456789012345","description":"A unique Akahu identity identifier."},"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"]},"Connection":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/ConnectionId"},"_classic":{"type":"string","format":"cuid","pattern":"^conn_[a-z0-9]{25,27}$","example":"conn_c01234567890123456789012344","description":"The ID of the corresponding classic connection for this institution.\n\nThis is only present for official open banking connections (Read more [here](/docs/official-open-banking))."},"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"},"new_connections_enabled":{"type":"boolean","description":"Whether new connections to this institution are allowed.\n\nThis may be `false` if your app is configured to migrate users to the official open banking connection for this provider.","example":true},"mode":{"type":"string","description":"The migration mode of this connection.\n\nThis is only present for official open banking connections (Read more [here](/docs/official-open-banking)).\n\nThe `mode` will be one of:\n\n- `strict` The classic equivalent of this connection is not available to your users. This mode can only be configured for new apps or apps that have successfully migrated all users away from their existing classic connections for this provider.\n\n- `migration` Any existing classic connections to this provider will continue to operate, but users will be unable to set up a new classic connection for this provider. New connections can only be established using this official open banking connection.\n\n- `side_by_side` Your users will be able to choose when setting up a new connection whether they wish to use the classic or official open banking connection for this provider. This mode is useful for apps that want to enable an official open banking connection where possible, but provide a fallback for users with account types that are not yet supported by the official open banking connection.\n\n- `developer` This is like migration mode, but will allow developers to continue to connect classic connections, so that they can test the migration process. This mode can only be enabled in non-production environments.","enum":["strict","migration","side_by_side","developer"],"example":"migration"},"deadline":{"type":"string","description":"The deadline date for users to migrate from classic to official open banking connections.\n\nThis is only present for official open banking connections in `migration` or `developer` mode (Read more [here](/docs/official-open-banking)).","example":"2025-12-31"}},"required":["_id","name","logo","connection_type","new_connections_enabled"]},"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"]},"Token":{"type":"object","description":"Granted token details","properties":{"success":{"type":"boolean","example":true},"access_token":{"type":"string","description":"Authorised **User Access Token** used to authenticate the user upon additional resource request.","example":"user_token_1111111111111111111111111"},"token_type":{"type":"string","description":"Type of authentication","example":"bearer"},"scope":{"type":"string","description":"whitespace separated string specifying the granted permissions and resources the given token has access to.","example":"IDENTITY_BASIC ACCOUNTS TRANSACTIONS"}}},"OneOffIdentityAccount":{"type":"object","description":"Identity Account","properties":{"bank":{"type":"string","description":"Display name of the bank","example":"Kiwibank"},"account_number":{"type":"string","description":"Unique bank account identifer","example":"38-9009-0000000-00"},"holder":{"type":"string","description":"Names of the owner of the account","example":"F BAGGINS"},"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}}},"Identities":{"type":"object","description":"Identity information derived from a user's connected accounts.","properties":{"name":{"type":"string","description":"Name of one of the account holders.","example":"F BAGGINS"},"formatted_account":{"type":"string","description":"Bank account number of the account this holder was derived from.","example":"38-9009-0000000-00"},"meta":{"type":"object","description":"Currently reserved for future use to house additional metadata about the user.","example":{}}}},"AddressComponents":{"type":"object","description":"Breakdown of the parts that make up this address.","properties":{"street":{"type":"string","description":"Street name from the address","example":"27 Bag End"},"suburb":{"type":"string","description":"Suburb name from the address","example":"Bagshot Row"},"city":{"type":"string","description":"City name from the address","example":"Hobbiton"},"region":{"type":"string","description":"Region name from the address","example":"Hobbiton"},"postal_code":{"type":"string","description":"Postal code from the address","example":1011},"country":{"type":"string","description":"Country from the address","example":"Middle Earth"}}},"AddressType":{"type":"string","example":"RESIDENTIAL","enum":["RESIDENTIAL","POSTAL","UNKNOWN"],"description":"Type of address:\n\n- `RESIDENTIAL` → Where the user lives.\n\n- `POSTAL` → Where the user can be reached by mail such as a PO-BOX.\n\n- `UNKNOWN` → Akahu was unable to determine which of the two types of address this is."},"Addresses":{"type":"object","description":"Address derived from a user's connected accounts.","properties":{"type":{"$ref":"#/components/schemas/AddressType"},"value":{"type":"string","description":"The raw address value provided by the bank.","example":"27 Bag End, Bagshot Row, Hobbiton, 1011"},"formatted_address":{"type":"string","description":"Optional parsed and formatted address string.","example":"27 Bag End, Bagshot Row, Hobbiton, Middle Earth, 1011"},"place_id":{"type":"string","description":"Google Places identifier from [Google Places API](https://developers.google.com/maps/documentation/places/web-service/overview).","example":"xxxxxxxxxxxxxxxxxxxxxxxxx"},"components":{"$ref":"#/components/schemas/AddressComponents","description":"Breakdown of the parts that make up this address."}}},"OneOffIdentity":{"type":"object","description":"One of Identity [Model](/docs/the-oneoff-identity-result-model)","properties":{"_id":{"$ref":"#/components/schemas/IdentityRequestId"},"status":{"type":"string","example":"PROCESSING","enum":["PROCESSING","COMPLETE","ERROR"],"description":"- `PROCESSING` → Identity request is in progress, continue to poll for a final state of `COMPLETE` or `ERROR`.\n\n- `COMPLETE` → Final success status reached and identity data has been returned.\n\n- `ERROR` → Final error status reached due to a fatal error occurred during processing.\n\nFor more details about one of identity statuses see:\n  - [📖 Identity Status reference](/docs/the-oneoff-identity-result-model#identity-status)"},"source":{"description":"The source / connection that provided the identity data.","$ref":"#/components/schemas/ConnectionInfo"},"accounts":{"type":"array","description":"Identity information registered on linked accounts","items":{"$ref":"#/components/schemas/OneOffIdentityAccount"}},"identities":{"type":"array","description":"List of identity information derived from a user's connected accounts.","items":{"$ref":"#/components/schemas/Identities"}},"addresses":{"type":"array","description":"List of addresses derived from a user's connected accounts.","items":{"$ref":"#/components/schemas/Addresses"}}}},"VerifyNameData":{"type":"object","properties":{"given_name":{"type":"string","description":"The given name/first name to match against, if available"},"middle_name":{"type":"string","description":"The middle name to match against, if available"},"family_name":{"type":"string","description":"The family name/surname to match against"},"initials":{"type":"array","items":{"type":"string"},"description":"An array of initials to match against, if available"}},"required":["family_name"],"example":{"given_name":"Homer","middle_name":"Jay","family_name":"Simpson"}},"VerifyNameMatchType":{"type":"string","enum":["MATCH","PARTIAL_MATCH"],"description":"What is the quality of the Match?\n - `MATCH` → All name components matched\n - `PARTIAL_MATCH` → Some of the name components matched, but not all"},"VerifyNameMatchedComponents":{"type":"object","properties":{"given_name":{"type":"boolean","description":"Did the given name match?"},"middle_name":{"type":"boolean","description":"Did the middle name match?"},"family_name":{"type":"boolean","description":"Did the family name match?"},"middle_initial":{"type":"boolean","description":"Did the middle initial match? (E.g. [B, J] matching Homer J Simpson)"},"given_initial":{"type":"boolean","description":"Did the given initial match? (E.g. [H, A] matching Homer J Simpson)"}},"required":["given_name","middle_name","family_name","middle_initial","given_initial"],"description":"A collection of flags indicating which name components matched","example":{"family_name":true,"middle_name":true,"given_name":true,"middle_initial":true,"given_initial":true}},"VerifyNamePartySource":{"type":"object","properties":{"type":{"type":"string","enum":["PARTY_NAME"],"description":"The name was matched against a Party"},"meta":{"type":"object","properties":{"value":{"type":"string","description":"The party name that was matched"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionId"},"description":"The connections with this name"}},"required":["value","sources"],"description":"The Party data that this name was verified against"},"match_result":{"$ref":"#/components/schemas/VerifyNameMatchType"},"verification":{"$ref":"#/components/schemas/VerifyNameMatchedComponents"}},"required":["type","meta","match_result","verification"],"example":{"type":"PARTY_NAME","meta":{"value":"Mr. Homer Jay Simpson","sources":["conn_ckhe08hru0000b8x179gg2v73"]},"match_result":"MATCH","verification":{"family_name":true,"middle_name":true,"given_name":true,"middle_initial":false,"given_initial":false}}},"VerifyNameHolderSource":{"type":"object","properties":{"type":{"type":"string","enum":["HOLDER_NAME"],"description":"The name was matched against an Account Holder"},"meta":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/AccountId"},"name":{"type":"string"},"formatted_account":{"type":"string"},"holder":{"type":"string"},"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}},"required":["_id","name","holder"],"description":"The Account data that this name was verified against"},"match_result":{"$ref":"#/components/schemas/VerifyNameMatchType"},"verification":{"$ref":"#/components/schemas/VerifyNameMatchedComponents"}},"required":["type","meta","match_result","verification"],"example":{"type":"HOLDER_NAME","meta":{"_id":"acc_ckuror24i000309l4z227e132","name":"Regular Account","formatted_account":"03-0481-0028919-00","holder":"MR H J SIMPSON","has_unlisted_holders":false},"match_result":"PARTIAL_MATCH","verification":{"family_name":true,"middle_name":false,"given_name":false,"middle_initial":true,"given_initial":true}}},"VerifyNameSource":{"oneOf":[{"$ref":"#/components/schemas/VerifyNamePartySource"},{"$ref":"#/components/schemas/VerifyNameHolderSource"}],"discriminator":{"propertyName":"type","mapping":{"PARTY_NAME":"#/components/schemas/VerifyNamePartySource","HOLDER_NAME":"#/components/schemas/VerifyNameHolderSource"}}},"VerifyNameResult":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/VerifyNameSource"}},"name":{"$ref":"#/components/schemas/VerifyNameData"}},"required":["sources","name"]}},"required":["success","item"]},{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"}},"required":["success"]}]},"OneOffIdentityParty":{"type":"object","properties":{"given_name":{"type":"string"},"middle_name":{"type":"string"},"family_name":{"type":"string"},"initials":{"type":"array","items":{"type":"string"}},"prefix":{"type":"string"},"gender":{"type":"string","enum":["MALE","FEMALE","UNKNOWN"]}},"description":"The Party data that this name was verified against"},"OneOffVerifyNamePartySource":{"type":"object","properties":{"type":{"type":"string","enum":["PARTY_NAME"],"description":"The name was matched against a Party"},"meta":{"$ref":"#/components/schemas/OneOffIdentityParty"},"match_result":{"$ref":"#/components/schemas/VerifyNameMatchType"},"verification":{"$ref":"#/components/schemas/VerifyNameMatchedComponents"}},"required":["type","meta","match_result","verification"],"example":{"type":"PARTY_NAME","match_result":"MATCH","meta":{"initials":["H","J"],"given_name":"Homer","middle_name":"Jay","family_name":"Simpson","prefix":"MR","gender":"MALE"},"verification":{"family_name":true,"middle_name":true,"given_name":true,"middle_initial":true,"given_initial":true}}},"OneOffVerifyNameHolderSource":{"type":"object","properties":{"type":{"type":"string","enum":["HOLDER_NAME"],"description":"The name was matched against an Account Holder"},"meta":{"allOf":[{"$ref":"#/components/schemas/OneOffIdentityAccount"},{"description":"The Account data that this name was verified against"}]},"match_result":{"$ref":"#/components/schemas/VerifyNameMatchType"},"verification":{"$ref":"#/components/schemas/VerifyNameMatchedComponents"}},"required":["type","meta","match_result","verification"],"example":{"type":"HOLDER_NAME","match_result":"PARTIAL_MATCH","meta":{"name":"Regular Account","holder":"Mr. Homer J Simpson","has_unlisted_holders":false,"account_number":"03-0481-0028919-00","bank":"Demo Bank"},"verification":{"family_name":true,"middle_name":false,"given_name":true,"middle_initial":true,"given_initial":false}}},"OneOffVerifyNameSource":{"oneOf":[{"$ref":"#/components/schemas/OneOffVerifyNamePartySource"},{"$ref":"#/components/schemas/OneOffVerifyNameHolderSource"}],"discriminator":{"propertyName":"type","mapping":{"PARTY_NAME":"#/components/schemas/OneOffVerifyNamePartySource","HOLDER_NAME":"#/components/schemas/OneOffVerifyNameHolderSource"}}},"OneOffVerifyNameResult":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/OneOffVerifyNameSource"}},"name":{"$ref":"#/components/schemas/VerifyNameData"}},"required":["sources","name"]}},"required":["success","item"]},{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"}},"required":["success"]}]},"TransactionType":{"type":"string","example":"EFTPOS","enum":["CREDIT","DEBIT","PAYMENT","TRANSFER","STANDING ORDER","EFTPOS","INTEREST","FEE","TAX","CREDIT CARD","DIRECT CREDIT","DIRECT DEBIT","ATM","LOAN"],"description":"Type of the transaction:\n\n  - `CREDIT` → Money has entered the account.\n\n  - `DEBIT` → Money has left the account.\n\n  - `PAYMENT` → Payment to an external account.\n\n  - `TRANSFER` → Transfer between accounts that are associated with the same credentials.\n\n  - `STANDING ORDER` → Automatic payment.\n\n  - `EFTPOS` → Payment made via an EFTPOS system.\n\n  - `INTEREST` → An interest payment.\n\n  - `FEE` → Fee payment to the account provider.\n\n  - `TAX` → Tax payment.\n\n  - `CREDIT CARD` → Credit card payment.\n\n  - `DIRECT DEBIT` → Direct debit payment.\n\n  - `DIRECT CREDIT` → Direct credit (someone paying into the account).\n\n  - `ATM` → ATM deposit or withdrawal.\n\n  - `LOAN` → Loan payment."},"CategoryGroups":{"type":"object","description":"Higher level groupings that a category belongs to.","additionalProperties":{"type":"object","properties":{"_id":{"type":"string","description":"The ID for this group of categories","example":"group_1111111111111111111111111"},"name":{"type":"string","description":"The name of this group of categories","example":"Lifestyle"}}},"example":{"personal_finance":{"_id":"group_1111111111111111111111111","name":"Lifestyle"}}},"Transaction":{"type":"object","required":["_id","_account","_connection","_user","date","description","amount","type","created_at","updated_at"],"properties":{"_id":{"type":"string","description":"The Akahu Transaction ID","example":"trans_1111111111111111111111111"},"_account":{"type":"string","description":"The Akahu Account ID that this transaction belongs to","example":"acc_1111111111111111111111111"},"_connection":{"type":"string","description":"The Akahu Connection ID that this transaction belongs to","example":"conn_1111111111111111111111111"},"_user":{"type":"string","description":"The Akahu User ID that this transaction belongs to","example":"user_1111111111111111111111111"},"_migrated":{"type":"string","description":"The Akahu Transaction ID that this transaction was migrated from.","example":"trans_1111111111111111111111110"},"_migrated_account":{"type":"string","description":"The Akahu Account ID that this transaction was migrated from.","example":"acc_1111111111111111111111110"},"created_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this transaction was retrieved and created by Akahu","example":"2020-01-01T01:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this transaction was last updated by Akahu","example":"2020-01-01T01:00:00.000Z"},"date":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this transaction was created by the bank","example":"2020-01-01T01:00:00.000Z"},"description":{"type":"string","description":"The raw transaction description, essentially what you see on a bank statement","example":"{ RAW TRANSACTION DESCRIPTION }"},"amount":{"type":"number","description":"How much money this transaction was for","example":-5.5},"balance":{"type":"number","description":"The account balance after the receipt of this transaction, where available","example":100},"type":{"$ref":"#/components/schemas/TransactionType"},"hash":{"type":"string","description":"This field is deprecated and should not be used. It is scheduled to be removed in future API versions.","deprecated":true},"merchant":{"type":"object","description":"The merchant that generated this transaction. Only present when you have permission to view enriched transactions.","properties":{"_id":{"type":"string","description":"The Akahu Merchant ID","example":"merchant_cm6pib1l5000i08lhfah11sht"},"name":{"type":"string","description":"The Akahu Merchant name","example":"Bob's Pizza"},"website":{"type":"string","format":"uri","description":"The Akahu Merchant website","example":"https://pizza.bob.nz"}}},"category":{"type":"object","description":"The base NZFCC category that the transaction belongs to. Also included is a map of less specific category groupings that this NZFCC category is part of (by default Akahu will include `personal_finance`). Custom category groupings can be configured for your application if required. Only present when you have permission to view enriched transactions.","properties":{"_id":{"type":"string","description":"The NZFCC Category ID","example":"nzfcc_1111111111111111111111111"},"name":{"type":"string","description":"The NZFCC Category Name","example":"Cafes & Restaurants"},"groups":{"$ref":"#/components/schemas/CategoryGroups"}}},"meta":{"type":"object","description":"Additional metadata we manage to retrieve for the transaction. Only present when you have permission to view enriched transactions. All fields are optional and provided on a \"best-effort\" basis.","properties":{"particulars":{"type":"string","description":"The particulars field set on this transaction.","example":"abc123"},"code":{"type":"string","description":"The code field set on this transaction.","example":"abc123"},"reference":{"type":"string","description":"The reference field set on this transaction.","example":"abc123"},"other_account":{"type":"string","description":"The formatted NZ bank account number of the other party to this transaction.","example":"00-0000-0000000-00"},"conversion":{"type":"object","description":"If this transaction was made in another currency, details about the currency conversion.","properties":{"amount":{"type":"number","description":"The amount transacted in the foreign currency","example":100},"currency":{"type":"string","description":"The (3 letter ISO 4217 currency code)[https://www.xe.com/iso4217.php] that was used for this transaction.","example":"GBP"},"rate":{"type":"number","description":"The foreign currency conversion rate applied to this transaction.","example":1.25}}},"card_suffix":{"type":"string","description":"If this transaction was made with a credit or debit card, the last four digits of the card number.","example":1234},"logo":{"type":"string","format":"uri","description":"URL of an image for this transaction. This is typically the logo of the transaction merchant. If no logo is available, a placeholder image is provided.","example":"https://cdn.akahu.nz/logos/merchants/merchant_cm6pib1l5000i08lhfah11sht"}}}}},"Category":{"type":"object","properties":{"_id":{"type":"string","description":"The NZFCC Category ID","example":"nzfcc_1111111111111111111111111"},"name":{"type":"string","description":"The NZFCC Category name","example":"Cafes & Restaurants"},"groups":{"$ref":"#/components/schemas/CategoryGroups"}}},"PendingTransaction":{"type":"object","properties":{"_account":{"type":"string","description":"The Akahu Account ID that this transaction belongs to","example":"acc_1111111111111111111111111"},"_connection":{"type":"string","description":"The Akahu Connection ID that this transaction belongs to","example":"conn_1111111111111111111111111"},"_user":{"type":"string","description":"The Akahu User ID that this transaction belongs to","example":"user_1111111111111111111111111"},"updated_at":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this transaction was last updated by Akahu","example":"2020-01-01T01:00:00.000Z"},"date":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp for the transaction from the bank.","example":"2020-01-01T01:00:00.000Z"},"description":{"type":"string","description":"The raw transaction description, essentially what you see on a bank statement","example":"{ RAW TRANSACTION DESCRIPTION }"},"amount":{"type":"number","description":"How much money this transaction was for","example":-5.5},"type":{"$ref":"#/components/schemas/TransactionType"},"meta":{"type":"object","description":"Additional metadata we manage to retrieve for the transaction. Only present when you have permission to view enriched transactions. All fields are optional and provided on a \"best-effort\" basis.","properties":{"particulars":{"type":"string","description":"The particulars field set on this transaction.","example":"abc123"},"code":{"type":"string","description":"The code field set on this transaction.","example":"abc123"},"reference":{"type":"string","description":"The reference field set on this transaction.","example":"abc123"},"other_account":{"type":"string","description":"The formatted NZ bank account number of the other party to this transaction.","example":"00-0000-0000000-00"},"conversion":{"type":"object","description":"If this transaction was made in another currency, details about the currency conversion.","properties":{"amount":{"type":"number","description":"The amount transacted in the foreign currency","example":100},"currency":{"type":"string","description":"The (3 letter ISO 4217 currency code)[https://www.xe.com/iso4217.php] that was used for this transaction.","example":"GBP"},"rate":{"type":"number","description":"The foreign currency conversion rate applied to this transaction.","example":1.25}}},"card_suffix":{"type":"string","description":"If this transaction was made with a credit or debit card, the last four digits of the card number.","example":1234}}}}},"Payment":{"type":"object","properties":{"_id":{"type":"string","description":"The Akahu Payment ID","example":"payment_1111111111111111111111111"},"from":{"type":"string","description":"The Akahu Account ID of the source account","example":"acc_1111111111111111111111111"},"to":{"type":"object","description":"Information about who this payment is to","properties":{"account_number":{"type":"string","description":"The NZ bank account number to whom this payment is made","example":"12-1234-1234567-12"},"name":{"type":"string","description":"The name of the account holder of the destination account","example":"John Smith","pattern":"^[A-Za-z0-9 \\-_]*$"}}},"amount":{"type":"number","format":"decimal","multipleOf":0.01,"description":"How much money the payment is for","example":9.51},"meta":{"type":"object","description":"Payment metadata that you have specified","properties":{"destination":{"type":"object","description":"Metadata that will appear in the destination account","properties":{"particulars":{"type":"string","description":"The particulars you have specified for the destination account","example":"destPart","pattern":"^[A-Za-z0-9 \\-_]*$"},"code":{"type":"string","description":"The code you have specified for the destination account","example":"destCode","pattern":"^[A-Za-z0-9 \\-_]*$"},"reference":{"type":"string","description":"The reference you have specified for the destination account","example":"destRef","pattern":"^[A-Za-z0-9 \\-_]*$"}}},"source":{"type":"object","description":"Metadata that will appear in the source account","properties":{"code":{"type":"string","description":"The code you have specified for the source account","example":"sourceCode","pattern":"^[A-Za-z0-9 \\-_]*$"},"reference":{"type":"string","description":"The reference you have specified for the source account","example":"sourceRef","pattern":"^[A-Za-z0-9 \\-_]*$"}}}}},"sid":{"type":"string","description":"Akahu's unique ID inserted into the particulars field","example":"akp111111111"},"status":{"type":"string","example":"READY","enum":["READY","SENT","PAUSED","DECLINED","CANCELLED","ERROR"],"description":"Status of the payment:\n- `READY` → Initial state payment is ready to be processed.\n\n- `SENT` → Payment initiated with the user's bank and we've received confirmation that it has been accepted.\n\n- `PAUSED` → Payment is not yet ready to be processed.\n\n- `DECLINED` → Payment has been declined by the user's bank.\n\n- `CANCELLED` → Payment was cancelled.\n\n- `ERROR` → Internal Akahu error occurred.\n\nFor more details see:\n  - [📚 Payments guide](/docs/making-a-payment)\n  - [📚 Payments lifecycle guide](/docs/making-a-payment#payment-lifecycle)"},"status_text":{"type":"string","description":"If available, more information about the payment's staus","example":"This payment has just been created and is ready to be sent"},"final":{"type":"boolean","description":"If this payment has reached it's final state","example":false},"timeline":{"type":"array","description":"A timeline of events regarding this payment","items":{"type":"object","description":"A timeline event","properties":{"status":{"type":"string","description":"The payment's status at this time","example":"READY"},"time":{"type":"string","format":"date-time","description":"An ISO 8701 timestamp of when this event was created","example":"2020-01-01T01:00:00.000Z"},"eta":{"type":"string","format":"date-time","description":"An ISO 8701 timestamp of when Akahu expects the payment to arrive. Only present on events for `SENT` statuses.","example":"2020-01-01T01:00:00.000Z"}}}},"created_at":{"type":"string","format":"date-time","description":"An ISO 8701 timestamp of when this payment was created","example":"2020-01-01T01:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"An ISO 8701 timestamp of when this payment was last updated by Akahu","example":"2020-01-01T01:00:00.000Z"},"received_at":{"type":"string","format":"date-time","description":"An ISO 8701 timestamp of when this payment was received by the destination account. This field will only be populated if the destination account is connected to Akahu.","example":"2020-01-01T01:00:00.000Z"}}},"Party":{"type":"object","required":["_id","_connection","_user","_authorisation","type"],"properties":{"_id":{"type":"string","description":"The unique identifier for this party"},"_connection":{"type":"string","description":"The connection ID. This identifies which financial institution this data was sourced from."},"_user":{"type":"string","description":"The Akahu user ID that identifies the user that this party is associated with."},"_authorisation":{"type":"string","description":"The authorisation identifier. Financial accounts are connected to Akahu via an authorisation with the user's financial institution. This identifier can be used to link specific financial accounts to the party who completed the authorisation by matching records with the same `_authorisation` value.","example":"authorisation_1111111111111111111111111"},"type":{"type":"string","deprecated":true,"description":"This field is included for legacy compatibility. It will always contain a fixed value of \"INDIVIDUAL\". Due to some quirks with the data held in bank systems, it is possible in rare cases that a company name is returned instead of an individual name. This can happen for small business accounts where bank staff have set up a user profile for a company instead of a person.","enum":["INDIVIDUAL"]},"name":{"type":"object","properties":{"value":{"type":"string","description":"The party's name as provided by their connected institution.","example":"Mr Frodo Baggins"}}},"dob":{"type":"object","properties":{"value":{"type":"string","format":"date","description":"The party's date-of-birth in the format YYYY-MM-DD.","example":"2001-12-20"}}},"tax_number":{"type":"object","properties":{"value":{"type":"string","pattern":"^[01]\\d{3}\\.\\d{3}\\.\\d{3}$","description":"The party's IRD number in the format XXX-XXX-XXX.","example":"123-456-789"}}},"phone_numbers":{"type":"array","items":{"type":"object","description":"A phone number that the party has registered with their connected institution.","properties":{"value":{"type":"string","description":"The phone number","example":"+642101234567"},"subtype":{"type":"string","enum":["MOBILE","HOME","WORK"]},"verified":{"type":"boolean"}}}},"email_addresses":{"type":"array","items":{"type":"object","description":"An email address that the party has registered with their connected institution.","properties":{"value":{"type":"string","description":"The email address","example":"frodo.baggins@aol.com"},"subtype":{"type":"string","enum":["PRIMARY"]},"verified":{"type":"boolean"}}}},"addresses":{"type":"array","items":{"type":"object","description":"An address that the party has registered with their connected institution.","properties":{"value":{"type":"string","description":"The raw address value from the connected institution."},"subtype":{"$ref":"#/components/schemas/AddressType"},"formatted":{"type":"string","description":"A consistently formatted/normalised version of the address."},"components":{"$ref":"#/components/schemas/AddressComponents"},"google_maps_place_id":{"type":"string","description":"Google Maps API Place ID for this address."}}}}}},"Me":{"type":"object","properties":{"_id":{"type":"string","description":"Unique Akahu user identifier.","example":"user_ck9uh3kex000107muemzpdkr7"},"access_granted_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted date of when the user granted access to the app","example":"2020-05-05T22:17:08.121Z"},"email":{"type":"string","format":"email","description":"Users email","example":"oliver@akahu.nz"}}},"Webhook":{"type":"object","properties":{"_id":{"type":"string","description":"Unique Akahu webhook identifier.","example":"hook_1111111111111111111111111"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp that the webhook was created.","example":"2020-04-08T23:15:39.917Z"},"updated_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp that the webhook was last updated.","example":"2020-04-08T23:15:39.917Z"},"last_called_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp of the last time your webhook endpoint was sent a webhook event.","example":"2020-04-08T23:15:39.917Z"},"state":{"type":"string","description":"Stored state upon creating a webhook and is made available on the webhook event allowing you to verify the event.\nCan be used to store a unique identifier related to your end user allowing you to determine on an arrival of a webhook event which user of your application needs to be updated or notified.","example":"foobarbaz"},"url":{"type":"string","format":"uri","description":"Endpoint to send registered webhook events to.","example":"https://webhooks.myapp.com/akahu"}}},"WebhookEvent":{"type":"object","properties":{"_id":{"type":"string","description":"Unique Akahu webhook event identifier.","example":"hook_1111111111111111111111111"},"hook":{"type":"string","description":"Unique Akahu webhook identifier.","example":"hook_1111111111111111111111111"},"status":{"type":"string","example":"FAILED","enum":["SENT","RETRY","FAILED"],"description":"Webhook event state\n- `SENT` Webhook has been sent and has been confirmed with a `200` response from the receiver.\n\n- `RETRY` Webhook has failed to send in a previous attempt but it will be retried.\n\n- `FAILED` Webhook has failed to send after attempted retries, due to not receiving a `200` response from the receiver."},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp that the webhook event was created.","example":"2020-04-08T23:15:39.917Z"},"updated_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp that the webhook event was last updated.","example":"2020-04-08T23:15:39.917Z"},"last_failed_at":{"type":"string","format":"date-time","description":"ISO 8601 formatted timestamp that the webhook event last failed.","example":"2020-04-08T23:15:39.917Z"},"payload":{"type":"object","description":"payload / event body sent to the `_hook`","properties":{"success":{"type":"boolean","example":true},"webhook_type":{"type":"string","example":"TOKEN","enum":["TOKEN","ACCOUNT","TRANSACTION","PAYMENT","TRANSFER"],"description":"Resource the webhook event is related to for more details checkout the [📖 Webhooks reference](/docs/reference-webhooks)"},"webhook_code":{"type":"string","description":"Webhook action dependant on the `webhook_type` for more details on our provided webhooks checkout the [📖 Webhooks reference](/docs/reference-webhooks)"}}}}},"AuthorisationRequestSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"request_uri":{"type":"string","description":"The pushed authorisation request_uri that should be specified in the authorisation URL."},"authorisation_url":{"type":"string","format":"uri","description":"A pre-built authorisation URL that the user can be redirected to for authorisation, this includes the request_uri and any other necessary query parameters."},"expires_in":{"type":"number","description":"The number of seconds until the request URI expires."}},"required":["success","request_uri","authorisation_url","expires_in"]},"OAuth400ErrorCode":{"type":"string","enum":["invalid_request","unsupported_response_type","unsupported_grant_type"]},"CreateAuthorisationRequestIssueCode":{"type":"string","enum":["invalid_request","not_found","single_limit_exceeded","invalid_payee","multiple_payees_not_supported","account_payment_from_unsupported"]},"IssuePath":{"type":"array","items":{"title":"IssuePathSegment","oneOf":[{"type":"string"},{"type":"number"}]}},"CreateAuthorisationRequestInvalidRequestResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/OAuth400ErrorCode"},"error_description":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/CreateAuthorisationRequestIssueCode"},"message":{"type":"string"},"path":{"$ref":"#/components/schemas/IssuePath"}},"required":["code","message","path"]}}},"required":["success","error","error_description"]},"OAuth401ErrorCode":{"type":"string","enum":["invalid_client"]},"OAuthUnauthorizedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/OAuth401ErrorCode"},"error_description":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/OAuth401ErrorCode"},"message":{"type":"string"},"path":{"$ref":"#/components/schemas/IssuePath"}},"required":["code","message","path"]}}},"required":["success","error","error_description"]},"OAuth500ErrorCode":{"type":"string","enum":["server_error"]},"OAuthInternalServerErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/OAuth500ErrorCode"},"error_description":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/OAuth500ErrorCode"},"message":{"type":"string"},"path":{"$ref":"#/components/schemas/IssuePath"}},"required":["code","message","path"]}}},"required":["success","error","error_description"]},"ConnectionIdArray":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionId"}},"ConnectionStub":{"type":"string","enum":["amex","amex:classic","anz","anz:classic","anz:official","asb","asb:classic","asb:official","bnz","bnz:classic","bnz:official","booster","booster:classic","coop","coop:classic","demo_bank","demo_bank:classic","demo_bank:official","fisher_funds","fisher_funds:classic","generate","generate:classic","hatch","hatch:classic","hatch:official","heartland","heartland:classic","ird","ird:classic","pie_funds","pie_funds:classic","kernel","kernel:classic","kiwibank","kiwibank:classic","kiwibank:official","latitude","latitude:classic","milford","milford:classic","nzhl","nzhl:classic","nzhl:official","rabobank","rabobank:classic","sbs","sbs:classic","sharesies","sharesies:classic","sharesight","sharesight:classic","simplicity","simplicity:classic","stake","stake:classic","superlife","superlife:classic","tsb","tsb:classic","westpac","westpac:classic","westpac:official","wise","wise:classic"]},"ConnectionStubArray":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionStub"}},"ConnectionsArray":{"anyOf":[{"$ref":"#/components/schemas/ConnectionIdArray"},{"$ref":"#/components/schemas/ConnectionStubArray"}],"description":"Which connections your application is requesting access to for this request.\nDefaults to connections enabled for your application."},"EnduringAccessScope":{"type":"string","enum":["user:basic","user:email","identity:name","identity:dob","identity:email","identity:phone","identity:address","identity:tax_number","accounts:basic","accounts:balance","accounts:details","accounts:owner","transactions:credits","transactions:debits","payments"]},"TransactionConstraints":{"type":"object","properties":{"start_date":{"type":"string","format":"date","description":"The start date for transactions to be requested from for new consents, this is in the Pacific/Auckland timezone."}},"required":["start_date"],"description":"Any constraints on transaction data that should be included in this access request, uses app defaults if not specified."},"EnduringPaymentFrequency":{"type":"string","enum":["DAILY","WEEKLY","FORTNIGHTLY","MONTHLY","ANNUALLY"],"description":"The frequency at which the periodic limit applies, this is used in combination with the amount to determine the periodic limit. (E.g. $1 daily)"},"EnduringPaymentPeriodLimit":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"The amount that can be paid in the specified frequency period."},"frequency":{"$ref":"#/components/schemas/EnduringPaymentFrequency"}},"required":["amount","frequency"],"description":"The periodic payment limit for payments initiated under this consent."},"BankAccountNumber":{"type":"string","pattern":"^\\d{2}-\\d{4}-\\d{7}-\\d{2,3}$"},"PaymentConsentStaticPayeeInput":{"type":"object","properties":{"source":{"type":"string","enum":["STATIC"]},"account_number":{"$ref":"#/components/schemas/BankAccountNumber"}},"required":["source","account_number"]},"PayeeId":{"type":"string","pattern":"^payee_[a-z0-9]{25,27}$","example":"payee_c01234567890123456789012345"},"PaymentConsentRegisteredPayeeInput":{"type":"object","properties":{"source":{"type":"string","enum":["REGISTERED"]},"_payee":{"$ref":"#/components/schemas/PayeeId"}},"required":["source","_payee"]},"PaymentConsentInlinePayeeInputNoneVerified":{"type":"object","properties":{"source":{"type":"string","enum":["INLINE"]},"account_number":{"$ref":"#/components/schemas/BankAccountNumber"},"name":{"type":"string","minLength":3,"maxLength":200},"verification_method":{"type":"string","enum":["NONE"],"description":" - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."}},"required":["source","account_number","name","verification_method"]},"PaymentConsentInlinePayeeInputClientVerified":{"type":"object","properties":{"source":{"type":"string","enum":["INLINE"]},"account_number":{"$ref":"#/components/schemas/BankAccountNumber"},"name":{"type":"string","minLength":3,"maxLength":200},"verification_method":{"type":"string","enum":["CLIENT_VERIFIED"],"description":" - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."}},"required":["source","account_number","name","verification_method"]},"PaymentConsentInlinePayeeInputVerifiedVerified":{"type":"object","properties":{"source":{"type":"string","enum":["INLINE"]},"verification_method":{"type":"string","enum":["VERIFICATION_TOKEN"],"description":" - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."},"verification_token":{"type":"string"}},"required":["source","verification_method","verification_token"]},"PaymentConsentInlinePayeeInput":{"oneOf":[{"$ref":"#/components/schemas/PaymentConsentInlinePayeeInputNoneVerified"},{"$ref":"#/components/schemas/PaymentConsentInlinePayeeInputClientVerified"},{"$ref":"#/components/schemas/PaymentConsentInlinePayeeInputVerifiedVerified"}],"discriminator":{"propertyName":"verification_method","mapping":{"NONE":"#/components/schemas/PaymentConsentInlinePayeeInputNoneVerified","CLIENT_VERIFIED":"#/components/schemas/PaymentConsentInlinePayeeInputClientVerified","VERIFICATION_TOKEN":"#/components/schemas/PaymentConsentInlinePayeeInputVerifiedVerified"}}},"EnduringPayee":{"anyOf":[{"$ref":"#/components/schemas/PaymentConsentStaticPayeeInput"},{"$ref":"#/components/schemas/PaymentConsentRegisteredPayeeInput"},{"$ref":"#/components/schemas/PaymentConsentInlinePayeeInput"}]},"EnduringAccessPaymentRequestApiView":{"type":"object","properties":{"single_limit":{"type":"number","exclusiveMinimum":0,"description":"The single payment limit for payments initiated under this consent."},"periodic_limit":{"$ref":"#/components/schemas/EnduringPaymentPeriodLimit"},"payees":{"type":"array","items":{"$ref":"#/components/schemas/EnduringPayee"},"minItems":1,"description":"The payees that are authorized to receive payments under this consent. At least one payee must be specified."}},"required":["single_limit","periodic_limit","payees"],"description":"The payment consent details for this request."},"EnduringAccessConstraints":{"type":"object","properties":{"transactions":{"$ref":"#/components/schemas/TransactionConstraints"},"payments":{"$ref":"#/components/schemas/EnduringAccessPaymentRequestApiView"}},"description":"Any constraints on this access request."},"EnduringAccessRequest":{"type":"object","properties":{"type":{"type":"string","enum":["enduring_access"]},"connections":{"$ref":"#/components/schemas/ConnectionsArray"},"scope":{"type":"array","items":{"$ref":"#/components/schemas/EnduringAccessScope"},"description":"Which scopes your application is requesting access for this request.\nDefaults to all scopes enabled for your application.\nIf the user already has a previous authorisation with less or more scopes, this will not trigger a replacement."},"constraints":{"$ref":"#/components/schemas/EnduringAccessConstraints"}},"required":["type"]},"AppTokenId":{"type":"string","pattern":"^app_token_[a-z0-9]{25,27}$","description":"Your App ID Token","example":"app_token_c01234567890123456789012345"},"EmailAddress":{"type":"string","format":"email"},"UserId":{"type":"string","pattern":"^user_[a-z0-9]{25,27}$","example":"user_c01234567890123456789012345"},"EnduringLoginHint":{"anyOf":[{"$ref":"#/components/schemas/EmailAddress"},{"$ref":"#/components/schemas/UserId"}],"description":"A login hint to suggest a user to use for 'enduring_access' requests. This will be ignored for other request types.\nThe user may choose to authenticate as a different Akahu user than specified.\nThis may be in the form of an email address or an Akahu User ID."},"OAuthRedirectMode":{"type":"string","enum":["default","embedded","deep_link"],"default":"default","description":"The mode of redirect to use when redirecting the user back to your application."},"OAuthResponseType":{"type":"string","enum":["code"],"description":"The response type to use for this request, only 'code' is supported."},"EnduringPaymentConstraints":{"type":"object","properties":{"label":{"type":"string","default":"Default","description":"The label that groups these payment constraints.\nThis is used to help distinguish between multiple payment consents for the same account.\nWhen re-consenting, this label will ensure that the old consent with the same label is replaced by the new one."},"single_limit":{"type":"number","exclusiveMinimum":0,"description":"The single payment limit for payments initiated under this consent."},"periodic_limit":{"$ref":"#/components/schemas/EnduringPaymentPeriodLimit"},"payees":{"type":"array","items":{"$ref":"#/components/schemas/EnduringPayee"},"minItems":1,"description":"The payees that are authorized to receive payments under this consent, at least one payee must be specified."}},"required":["single_limit","periodic_limit","payees"],"description":"The payment consent details for this request."},"EnduringPaymentConsentRequest":{"type":"object","properties":{"type":{"type":"string","enum":["enduring_payment_consent"]},"_user":{"$ref":"#/components/schemas/UserId"},"_account":{"$ref":"#/components/schemas/AccountId"},"payment_consent":{"$ref":"#/components/schemas/EnduringPaymentConstraints"}},"required":["type","_user","_account"]},"AccessRequest":{"oneOf":[{"$ref":"#/components/schemas/EnduringAccessRequest"},{"$ref":"#/components/schemas/EnduringPaymentConsentRequest"}],"discriminator":{"propertyName":"type","mapping":{"enduring_access":"#/components/schemas/EnduringAccessRequest","enduring_payment_consent":"#/components/schemas/EnduringPaymentConsentRequest"}}}}},"tags":[{"name":"Auth"},{"name":"Accounts"},{"name":"Authorisations"},{"name":"Categories"},{"name":"Connections"},{"name":"Data Refresh"},{"name":"Identity"},{"name":"Payments"},{"name":"Transactions"},{"name":"Me"},{"name":"Webhooks"},{"name":"Support"}],"paths":{"/accounts":{"get":{"tags":["Accounts"],"summary":"List all accounts","security":[{"user_token":[]}],"description":"Get a list of all accounts 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"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Account"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/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"}}}},"/accounts/{id}/verification-token":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Account ID","example":"acc_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Accounts"],"summary":"Get account verification token","security":[{"user_token":[]}],"description":"Get an account verification token for an account so it can be used as a payee in either a one-off payment or enduring payment consent request.\n\nAccount verification tokens can only be generated for BECS-identifiable bank accounts (i.e. regular NZ bank accounts) and require that your application has permission to read the account holder name.","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"type":"string"}}}}}},"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"}}},"delete":{"tags":["Accounts"],"summary":"Revoke access to account","deprecated":true,"security":[{"user_token":[]}],"description":"> ⚠️\n>\n> This endpoint is deprecated.\n> <pre></pre>\n> Accounts connected via an official open banking connection can't be revoked on an individual basis via API. Calling this endpoint for accounts that have a `connection_type` of `official` will result in a 400 error response.\n> <pre></pre>\n> Use one of these alternative options to the update the accounts connected via `official` connections:\n>  - Send the user to the [📚 authorisation flow](/docs/authorizing-with-oauth2) where they can reduce the scope of the authorisation via their bank.\n>  - Use the [Revoke Access To Authorisation](/reference/delete_authorisations-id) endpoint to revoke the entire authorisation.\n\nRevoke your application's access to one of the user's connected accounts and its associated data, including transactions.\n\nUse this if you no longer require access to the consented account data.\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"}}},"example":{"success":true}}}},"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"}}}},"/accounts/{id}/payment-consents/{consent_id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Account ID","example":"acc_1111111111111111111111111","schema":{"type":"string"}},{"name":"consent_id","in":"path","required":true,"description":"An Akahu Payment Consent ID","example":"consent_1111111111111111111111111","schema":{"type":"string"}}],"delete":{"tags":["Accounts"],"summary":"Revoke a payment consent","security":[{"user_token":[]}],"description":"Revoke one of the enduring payment consents granted for an account.\n\nYou can find the `_id` of a consent by looking at the `payment_consents` array on the [account](/reference/get_accounts-id) it belongs to.\n\nRevoking a consent immediately prevents it from being used to initiate any further payments. This does not affect any other consents on the account, or the account's connection to your application.\n\nFor more details see:\n  - [📚 Requesting Payment Consent guide](/docs/enduring-payments-authorisation)\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"}}},"example":{"success":true}}}},"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"}}}},"/authorisations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Authorisation ID","example":"authorisation_1111111111111111111111111","schema":{"type":"string"}}],"delete":{"tags":["Authorisations"],"summary":"Revoke access to authorisation","security":[{"user_token":[]}],"description":"A user's accounts are connected to Akahu via an authorisation with their financial institution. Multiple accounts can be connected using a single authorisation.\n\nThis endpoint will revoke your application's access to one of the user's consented authorisations. After calling this endpoint, your application will no longer have access to the accounts connected via that authorisation (including their associated data and transactions).\n\nYou can find an authorisation for an account by looking at the `_authorisation` field on each account.\n\n> ℹ️\n>\n> Users can also update their authorisations via the [📚 authorisation flow](/docs/authorizing-with-oauth2). The authorisation flow is the only way that users can add or remove access for individual accounts rather than a whole authorisation.\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"}}},"example":{"success":true}}}},"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"}}}},"/token":{"post":{"tags":["Auth"],"summary":"Exchange an Authorization Code","security":[],"description":"This endpoint is the final step in our [📖 OAuth Authentication Flow](/docs/authorizing-with-oauth2).\n\nUse this endpoint to exchange an **Authorization Code** for a **User Access Token**, which can be used to access the rest of this API.\n\nTo ensure that your application does not retain unnecessary access to user data, [revoke](./delete_token) this access token in the event that is no longer required (e.g. the user deletes their account).\n\n**Endpoint not applicable for Personal Apps**. See our [📚 Getting started guide](/docs/getting-started) to set up your Personal App.\n\n> 📘\n>\n> **OAuth2 Error Responses**\n>\n> In keeping with the OAuth2 specification, error responses from this endpoint contain an error in the `error` field, rather than the `message` field used by other Akahu endpoints.\n\nFor more details see:\n- [📚 OAuth Authentication Flow](/docs/authorizing-with-oauth2).\n- [📖 Auth scopes](/docs/scopes)\n- [📖 Token webhooks](/docs/reference-webhooks#token)\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📚 Accessing account data guide](/docs/accessing-account-data)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type","code","redirect_uri","client_id","client_secret"],"properties":{"grant_type":{"type":"string","description":"Must always be `authorization_code`","example":"authorization_code"},"code":{"type":"string","description":"The code to be exchanged for a **User Access Token**, received upon the user's completion of the authorization redirect flow.","example":"code"},"redirect_uri":{"type":"string","description":"Same `redirect_uri` you specified to start the OAuth flow to receive an exchange code.","example":"http://localhost:3000/redirect"},"client_id":{"type":"string","description":"Your Akahu **App ID Token**","example":"{{app_auth}}"},"client_secret":{"type":"string","description":"Your Akahu **App Secret**","example":"{{appSecret}}"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"description":"Granted token details","$ref":"#/components/schemas/Token"}}}},"400":{"description":"Your request was malformed or otherwise unacceptable. The `error` key in the response will be on one of the standard OAuth error codes.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"examples":{"invalid_client":{"summary":"Invalid Client.","description":"The `client_id` is invalid.","value":{"success":false,"error":"invalid_client"}},"invalid_grant":{"summary":"Invalid Grant.","description":"There is something wrong with this OAuth request. Ensure you're following the specification.","value":{"success":false,"error":"invalid_grant"}},"expired_grant":{"summary":"Expired Grant.","description":"This code has expired.","value":{"success":false,"error":"expired_grant"}},"invalid Request":{"summary":"Invalid Request.","description":"This request is invalid. Ensure you're following the specification.","value":{"success":false,"error":"invalid Request"}},"unsupported_grant_type":{"summary":"Unsupported Grant Type","description":"The grant type must always be `authorization_code`","value":{"success":false,"error":"unsupported_grant_type"}}}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":false,"error":"server_error"}}}}}},"delete":{"tags":["Auth"],"summary":"Revoke a token","security":[{"user_token":[]}],"description":"Revokes the **User Access Token** that is included in the `Authorization` header of the request.\n\nRevoking a User Access Token will remove your access to **all** of a user's connected account data including transactions.\n\n> ℹ️\n>\n> Users can re-authorize your application's access to their accounts via the [📚 authorisation flow](/docs/authorizing-with-oauth2).","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/par":{"post":{"summary":"Create a pushed authorisation request","tags":["Auth"],"deprecated":false,"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"$ref":"#/components/schemas/AppTokenId"},"client_secret":{"type":"string","description":"Your App Secret"},"login_hint":{"$ref":"#/components/schemas/EnduringLoginHint"},"redirect_uri":{"type":"string","format":"uri","description":"The redirect URI to use when redirecting the user back to your application."},"redirect_mode":{"$ref":"#/components/schemas/OAuthRedirectMode"},"response_type":{"$ref":"#/components/schemas/OAuthResponseType"},"state":{"type":"string","description":"Any request state that should be passed back to your application when redirecting."},"correlation_id":{"type":"string"},"request":{"$ref":"#/components/schemas/AccessRequest"}},"required":["client_id","client_secret","redirect_uri","response_type","request"]},"example":{"client_id":"app_token_123","client_secret":"supersecret","request":{"type":"enduring_access","scope":["accounts:basic","accounts:balance","accounts:owner","identity:name"],"connections":["anz","asb","bnz","westpac","kiwibank","nzhl"]},"login_hint":"user_123","redirect_uri":"https://example.com/callback","response_type":"code","state":"my_encrypted_state"}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"client_id":{"$ref":"#/components/schemas/AppTokenId"},"client_secret":{"type":"string","description":"Your App Secret"},"login_hint":{"$ref":"#/components/schemas/EnduringLoginHint"},"redirect_uri":{"type":"string","format":"uri","description":"The redirect URI to use when redirecting the user back to your application."},"redirect_mode":{"$ref":"#/components/schemas/OAuthRedirectMode"},"response_type":{"$ref":"#/components/schemas/OAuthResponseType"},"state":{"type":"string","description":"Any request state that should be passed back to your application when redirecting."},"correlation_id":{"type":"string"},"request":{"$ref":"#/components/schemas/AccessRequest"}},"required":["client_id","client_secret","redirect_uri","response_type","request"]},"example":"client_id=app_token_123&client_secret=supersecret&request=%7B%22type%22%3A%22enduring_access%22%2C%22scope%22%3A%5B%22accounts%3Abasic%22%2C%22accounts%3Abalance%22%2C%22accounts%3Aowner%22%2C%22identity%3Aname%22%5D%2C%22connections%22%3A%5B%22anz%22%2C%22asb%22%2C%22bnz%22%2C%22westpac%22%2C%22kiwibank%22%2C%22nzhl%22%5D%7D&login_hint=user_123&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&state=my_encrypted_state"}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorisationRequestSuccessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorisationRequestInvalidRequestResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthUnauthorizedResponse"}}}},"415":{"description":"Unsupported media type"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthInternalServerErrorResponse"}}}}}}},"/connections":{"get":{"tags":["Connections"],"summary":"Get all connections","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGets a list of all connected financial institutions that users can connect to your Akahu application.\n\n- [📚 Supported Integrations List](/docs/integrations#supported-integrations)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"items":{"type":"array","description":"List all financial institutions that users can connect to your application.","items":{"$ref":"#/components/schemas/Connection"},"example":[{"_id":"conn_cjgaaqcna000001ldwof8tvj0","name":"ASB","logo":"https://cdn.akahu.nz/logos/connections/conn_cjgaaqcna000001ldwof8tvj0","connection_type":"classic","new_connections_enabled":false},{"_id":"conn_cm4hlog270000914n33hj6tqq","_classic":"conn_cjgaaqcna000001ldwof8tvj0","name":"ASB","logo":"https://cdn.akahu.nz/logos/connections/conn_cm4hlog270000914n33hj6tqq","connection_type":"official","new_connections_enabled":true,"mode":"migration","deadline":"2025-12-31"}]}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/connections/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Connection ID","example":"conn_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Connections"],"summary":"Get a connection","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGet an individual financial institution connection.\n\n- [📚 Supported Integrations List](/docs/integrations#supported-integrations)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"item":{"description":"Information about a specific financial institution that can be connected via Akahu","$ref":"#/components/schemas/Connection"}}}}}},"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"}}}},"/categories":{"get":{"tags":["Categories"],"summary":"Get all categories","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGets a list of all NZFCC categories that may be returned on a transaction.\n\n- [📚 Explore NZFCC Categories](https://nzfcc.org)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"items":{"type":"array","description":"List all NZFCC Categories.","items":{"$ref":"#/components/schemas/Category"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An NZFCC Category ID","example":"nzfcc_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Categories"],"summary":"Get category","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGet an individual NZFCC Category.\n\n- [📚 Explore NZFCC Categories](https://nzfcc.org)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"item":{"description":"Information about a specific NZFCC Category","$ref":"#/components/schemas/Category"}}}}}},"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"}}}},"/refresh":{"post":{"tags":["Data Refresh"],"summary":"Refresh all accounts","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"description":"This endpoint requests a data refresh for all accounts that the user has connected to your application.\n\nAccount data such as balance and transactions are periodically refreshed by Akahu and enriched **asynchronously**, providing clean and consistent data across financial institutions.\n\nHowever, there may be certain times that your app requires the most up-to-date account data possible, this endpoint allows you to request a refresh on-demand for these cases.\n\nFor more details see:\n- [📚 Data Refreshes guide](/docs/data-refreshes)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"description":"You have been rate limited on this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":false,"message":"Refresh initiated within last 5 minutes"}}}},"500":{"$ref":"#/components/responses/500"}}}},"/refresh/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Account or Connection ID","examples":{"account_id":{"summary":"Akahu Account ID","value":"acc_1111111111111111111111111"},"connection_id":{"summary":"Akahu Connection ID","value":"conn_1111111111111111111111111"}},"schema":{"type":"string"}}],"post":{"tags":["Data Refresh"],"summary":"Refresh Individual Accounts or Connections","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"description":"This endpoint requests a data refresh for a specific financial institution or a specific account that the user has connected to your application.\n\n#### Connection ID\n\nCalling this endpoint with a **Connection** ID will request that Akahu performs a data refresh for all of the user's connected accounts that are held at the financial institution corresponding to that Connection.\n\n#### Account ID\n\nCalling this endpoint with an **Account** ID will request that Akahu performs a data refresh for that specific connected account and any other connected accounts that are associated with the same login credentials.\n\nFor example, if the user has shared three ASB accounts from a single set of login credentials and you request a refresh for one, the other two accounts will also be refreshed.\n\nFor more details see:\n- [📚 Data Refreshes guide](/docs/data-refreshes)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"You have been rate limited on this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":false,"message":"Refresh initiated within last 5 minutes"}}}},"500":{"$ref":"#/components/responses/500"}}}},"/identity/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The authorization `code` received from the identity OAuth redirect.","schema":{"type":"string"}}],"get":{"tags":["Identity"],"summary":"[One-off access] Get identity result","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGet the results of an Identity OAuth result using the authorization `code` provided upon redirection to your `redirect_uri` after the user's successful completion of the authorisation flow.\n\nThis can be used to verify a user's identity using the data that is held about them by their financial institution.\n\nFor more information about our Identity OAuth flow see our:\n  - [📚 One-off Identity guide](/docs/oneoff-identity-verification)\n  - [📚 Identity verification guide](/docs/identity-verification)\n  - [📖 Identity model](/docs/the-oneoff-identity-result-model)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"$ref":"#/components/schemas/OneOffIdentity"}}}}}},"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"}}}},"/identity/{id}/verify/name":{"post":{"tags":["Identity"],"summary":"[One-off access] Verify a name","description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nTo verify your user's identity, you may wish to match the name that you have on file against an official record such as the bank account holder name or Party name, returned via the Identity Response.\n\nFor more details about the data returned, see:\n  - [📚 One-Off Verify Name](/docs/oneoff-verify-name)\n  - [📖 Identity model](/docs/the-oneoff-identity-result-model)","security":[{"app_auth":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/IdentityRequestId"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyNameData"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneOffVerifyNameResult"}}}},"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"}}}},"/verify/name":{"post":{"tags":["Identity"],"summary":"[Enduring access] Verify a name","description":"To verify your user's identity, you may wish to match the name that you have on file against an official record such as the bank account holder name or Party name.\n\nThis will match against all available sources from all accounts that the user has connected to your app.\n\nFor more details about the data returned, see:\n  - [📚 Enduring Verify Name](/docs/enduring-verify-name)","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyNameData"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyNameResult"}}}},"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"}}}},"/verify/name/{id}":{"post":{"tags":["Identity"],"summary":"[Enduring access] Verify a name against an account","description":"To verify your user's identity, you may wish to match the name that you have on file against an official record such as the bank account holder name or Party name.\n\nThis will only use identity sources derived from the specified account, rather than all accounts.\n\nFor more details about the data returned, see:\n  - [📚 Enduring Verify Name](/docs/enduring-verify-name)","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"schema":{"$ref":"#/components/schemas/AccountId"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyNameData"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyNameResult"}}}},"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"}}}},"/parties":{"get":{"tags":["Identity"],"summary":"[Enduring access] Get user identity data","security":[{"user_token":[]}],"description":"Get a list of the parties who have authorised financial account connections with your app. This data is sourced from the customer profile information held by the financial institution rather than any specific account held within.\n\n> ⚠️\n>\n> This data relates to the party that authorised the account connection as reported by the financial institution. Due to some quirks with the data held in bank systems, it is possible in rare cases that company details are returned instead of an individual person's. This can happen for small business bank accounts where a single shared login is set up for the company (rather than a proper company setup where staff have separate logins).","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/Party"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/payments":{"get":{"tags":["Payments"],"summary":"List payments","security":[{"user_token":[]}],"description":"Get a list of the payments that your application has initiated on behalf of the user within the `start` and `end` time range.\n\n>️ ℹ️ Time range defaults to the last 30 days.\n\nFor more details about payments see:\n  - [📖 Making a payment guide](/docs/making-a-payment)\n  - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle)\n  - [📚 Payment webhooks](/docs/reference-webhooks#payment)","parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"name":"start","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 Date","example":"2020-01-01T01:00:00.000Z"},{"name":"end","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 Date","example":"2020-02-01T01:00:00.000Z"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}},"post":{"tags":["Payments"],"summary":"Make a payment","security":[{"user_token":[]}],"description":"Initiate a payment from the user's connected bank account to another New Zealand bank account.\n\nThe payee bank account is not required to be connected to Akahu.\n\nFor more details about payments see:\n  - [📚 Making a payment guide](/docs/making-a-payment)\n  - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle)\n  - [📖 Payment webhooks](/docs/reference-webhooks#payment)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to","amount"],"properties":{"from":{"type":"string","description":"The Akahu Account ID you want to pay from","example":"acc_1111111111111111111111111"},"to":{"type":"object","description":"Account details specifying who you'd like to pay to","properties":{"name":{"type":"string","description":"The name of the person or company you want to pay","example":"Sammy Sample"},"account_number":{"type":"string","description":"The NZ bank account number you want to pay","example":"01-2345-6789012-00"}}},"amount":{"type":"number","description":"The payment amount","example":9.5},"meta":{"type":"object","description":"Metadata relating to the payment including references for both `source` (from) and `destination` (to).\n\nFor more details check out the [📚 Payment PCR Fields guide](/docs/making-a-payment#payment-pcr-fields).","properties":{"source":{"type":"object","properties":{"code":{"type":"string","description":"The `Code` field on the source statement","example":"code"},"reference":{"type":"string","description":"The `Reference` field on the source statement","example":"reference"}}},"destination":{"type":"object","properties":{"particulars":{"type":"string","description":"The `Particulars` field on the destination statement. Including this field will disable [📖 arrival tracking](/docs/making-a-payment#payment-arrival-tracking) on this payment."},"code":{"type":"string","description":"The `Code` field on the destination statement","example":"code"},"reference":{"type":"string","example":"reference","description":"The `Reference` field on the destination statement"}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"$ref":"#/components/parameters/ContentType"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"$ref":"#/components/schemas/Payment"},"item_id":{"type":"string","example":"payment_1111111111111111111111111","deprecated":true,"description":"⚠️ **Deprecated**\nThe Akahu Payment ID replaced via `item._id`"},"status":{"type":"string","example":"READY","deprecated":true,"description":"⚠️ **Deprecated**\nThe Akahu Payment status replaced via `item.status`"}}}}}},"400":{"description":"Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"examples":{"invalid_pcr":{"summary":"Invalid PCR Characters","description":"Unsupported characters were supplied for the particulars, code or reference. These fields only support [A-Z][a-z][0-9]-_ and spaces.","value":{"success":false,"message":"Invalid characters in `meta.source.code`"}},"hit_app_limit":{"summary":"Payment Above App Limit","description":"This payment is higher than your app's payment limit.","value":{"success":false,"message":"Payment above app limit"}},"hit_daily_limit":{"summary":"Payment Above Daily Limit","description":"Payment above app daily limit.","value":{"success":false,"message":"Payment above app daily limit"}},"unable_to_pay":{"summary":"Source Unable To Pay","description":"The source account is unable to make payments (eg. some savings accounts, kiwisavers, etc.).","value":{"success":false,"message":"from account is unable to make payments"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/payments/ird":{"post":{"tags":["Payments"],"summary":"Make a payment to IRD","security":[{"user_token":[]}],"description":"Initiate a tax payment from user's connected bank account to [🔗 Inland Revenue Department](https://www.ird.govt.nz/).\n\nFor more details about payments see:\n  - [📚 Making a payment guide](/docs/making-a-payment)\n  - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle)\n  - [📖 Payment webhooks](/docs/reference-webhooks#payment)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","amount","meta"],"properties":{"from":{"type":"string","description":"The Akahu Account ID you want to pay from","example":"acc_1111111111111111111111111"},"amount":{"type":"number","description":"The payment amount","example":9.5},"meta":{"type":"object","description":"Metadata relating to the tax payment.","required":["tax_number","tax_type"],"properties":{"tax_number":{"type":"string","minLength":8,"maxLength":10,"example":"123-456-789","description":"The 9-digit IRD or GST number that the payment relates to"},"tax_type":{"type":"string","minLength":3,"maxLength":3,"example":"DED","description":"The 3 character IRD tax type code that tells IRD what tax account the payment is for.\n\nFor a full list of tax types check out the [🔗 IRD's account type guide](https://www.ird.govt.nz/managing-my-tax/make-a-payment/choosing-the-right-account-type) for more details."},"tax_period":{"type":"string","example":"2022-01-31","description":"The end date of the tax period which this payment is for, formatted as an ISO 8601 date e.g. 1970-01-01. This is required by IRD for most tax payments, however there are certain payment types that do not require it (e.g. ARR, KSS, LGL). For the complete list of exclusions see the [IRD website](https://www.ird.govt.nz/managing-my-tax/make-a-payment/ways-of-paying/paying-electronically)"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"$ref":"#/components/parameters/ContentType"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"$ref":"#/components/schemas/Payment"},"item_id":{"type":"string","description":"⚠️ **Deprecated**\nThe Akahu Payment ID replaced via `item._id`","example":"payment_1111111111111111111111111","deprecated":true},"status":{"type":"string","description":"⚠️ **Deprecated**\nThe Akahu Payment status replaced via `item.status`","example":"READY","deprecated":true}}},"example":{"success":true,"item":{"_id":"payment_1111111111111111111111111","amount":9.5,"created_at":"2022-04-20T01:55:41.674Z","final":false,"from":"acc_1111111111111111111111111","sid":"akp1111111111","status":"READY","meta":{"destination":{"particulars":"123-456-789","code":"DED 31012022"},"source":{"code":"DED 31012022","reference":"123-456-789"}},"timeline":[{"status":"READY","time":"2022-04-20T01:55:41.674Z"}],"to":{"name":"Inland Revenue Department","account_number":"03-0049-0001100-27"},"updated_at":"2022-04-20T01:55:41.674Z"}}}}},"400":{"description":"Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"examples":{"invalid_pcr":{"summary":"Invalid tax number","description":"The provided tax number contains invalid characters","value":{"success":false,"message":"meta.tax_number may only contain digits and hyphens"}},"hit_app_limit":{"summary":"Payment Above App Limit","description":"This payment is higher than your app's payment limit.","value":{"success":false,"message":"Payment above app limit"}},"hit_daily_limit":{"summary":"Payment Above Daily Limit","description":"Payment above app daily limit.","value":{"success":false,"message":"Payment above app daily limit"}},"unable_to_pay":{"summary":"Source Unable To Pay","description":"The source account is unable to make payments (eg. some savings accounts, kiwisavers, etc.).","value":{"success":false,"message":"from account is unable to make payments"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/payments/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Payment ID","example":"payment_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Payments"],"summary":"Get a payment","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"description":"Get an individual payment that your application has initiated on behalf of the user.\n\nFor more details about payments see:\n  - [📖 Making a payment guide](/docs/making-a-payment)\n  - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle)\n  - [📚 Payment webhooks](/docs/reference-webhooks#payment)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"$ref":"#/components/schemas/Payment"}}}}}},"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"}}}},"/transactions":{"get":{"tags":["Transactions"],"summary":"Get transactions","security":[{"user_token":[]}],"description":"Get a list of the user's transactions within the `start` and `end` time range.\n\nThis endpoint returns **settled**\\* transactions for all accounts that the user has connected to your application. See [`GET /transactions/pending`](/reference/get_transactions-pending) to also query **pending** transactions.\n\n**Some important things to know about this endpoint**:\n- The data returned may vary depending on your app's permissions.\n- All transactions timestamps are in **UTC**.\n- If `start` and `end` are not provided, all available transactions will be returned.\n- The `start` query parameter is **exclusive**.\n- The `end` query parameter is **inclusive**.\n- All timestamps use **millisecond** resolution (i.e. `2025-01-01T11:59:59.999Z` is the instant before `2025-01-01T12:00:00.000Z`).\n\n**Further reading**:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📚 Pagination guide](/docs/accessing-transactional-data#pagination)\n- [📖 Transaction model](/docs/the-transaction-model)\n- [📖 Transaction webhooks](/docs/reference-webhooks#transaction)\n\n> \\*Both inbound and outbound transactions relating to [payments](/docs/making-a-payment) initiated via Akahu skip the `/transactions/pending` endpoint and are immediately available at this endpoint instead. This ensures that such transactions receive a stable `_id` field to assist with reconciliation. Their availability at this endpoint does not guarantee that the bank has undertaken final processing of the transaction.","parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"name":"start","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-01-01T12:00:00.000Z"},{"name":"end","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-02-01T12:00:00.000Z"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from an earlier query","example":"abc123"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"cursor":{"type":"object","properties":{"next":{"type":"string","description":"The cursor to get the next results"}}}}},"examples":{"unenriched":{"summary":"Unenriched","description":"Raw transactions, like what you would get from the bank.","value":{"success":true,"cursor":{"next":"abc123"},"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS"}]}},"enriched":{"summary":"Enriched","description":"Transactions that have been enriched by Akahu.","value":{"success":true,"cursor":{"next":"abc123"},"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS","merchant":{"_id":"merchant_1111111111111111111111111","name":"Bob's Pizza"},"category":{"_id":"nzfcc_1111111111111111111111111","name":"Cafes and restaurants","groups":{"personal_finance":{"_id":"group_clasr0ysw0011hk4m6hlk9fq0","name":"Lifestyle"}}},"meta":{"logo":"https://cdn.akahu.nz/logos/merchants/default.png","particulars":"...","code":"...","reference":"...","other_account":"00-0000-0000000-00","conversion":{"amount":2,"currency":"GBP","rate":2.75},"card_suffix":"1234"}}]}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/transactions/pending":{"get":{"tags":["Transactions"],"summary":"Get pending transactions","security":[{"user_token":[]}],"description":"Get a list of pending transactions from a user's connected accounts.\n\nThis endpoint returns pending transactions from all of a user's accounts that the user has connected to your application.\n\nPending transactions are not stable (eg. the date or description may change) due to the unreliable nature of the underlying NZ bank data.\n\n>️ ℹ️ You can tell when we last fetched a transaction by looking at it's `updated_at` key.\n\n- All transactions timestamps are in **UTC**.\n\nFor more details see:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📚 Pending transactions guide](/docs/accessing-transactional-data#pending-transactions)\n- [📖 Transaction model](/docs/the-transaction-model)","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingTransaction"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/transactions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Transaction ID","example":"trans_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Transactions"],"summary":"Get a transaction by ID","security":[{"user_token":[]}],"description":"Get a single transaction from one of the user's connected accounts.\n\n- Transactions will look different depending on your app's permissions.\n- All times on the transaction are in **UTC**.\n\nFor more details see:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📖 Transaction model](/docs/the-transaction-model)\n- [📖 Transaction webhooks](/docs/reference-webhooks#transaction)","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"type":"object","$ref":"#/components/schemas/Transaction"}}},"examples":{"unenriched":{"summary":"Unenriched","description":"Raw transactions, like what you would get from the bank.","value":{"success":true,"item":{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS"}}},"enriched":{"summary":"Enriched","description":"Transactions that have been enriched by Akahu.","value":{"success":true,"item":{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS","merchant":{"_id":"merchant_1111111111111111111111111","name":"Bob's Pizza"},"category":{"_id":"nzfcc_1111111111111111111111111","name":"Cafes and restaurants","groups":{"personal_finance":{"_id":"group_clasr0ysw0011hk4m6hlk9fq0","name":"Lifestyle"}}}}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/accounts/{id}/transactions":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Account ID","example":"acc_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Transactions"],"summary":"Get transactions by account","security":[{"user_token":[]}],"description":"Get a list of the user's transactions for a specific connected account within the `start` and `end` time range.\n\nThis endpoint returns **settled** transactions. See [`GET /accounts/{id}/transactions/pending`](/reference/get_accounts-id-transactions) to also query **pending** transactions for the account.\n\n>️ ℹ️ Time range defaults to the entire range [accessible to your app](/docs/accessing-transactional-data#getting-a-date-range).\n\nSome important things to know when querying transactions:\n- Transactions will look different depending on your app's permissions.\n- All transactions timestamps are in **UTC**.\n- The `start` query parameter is **exclusive**.\n- The `end` query parameter is **inclusive**.\n- All Akahu timestamps use **millisecond** resolution (i.e. `2025-01-01T11:59:59.999Z` is the instant before `2025-01-01T12:00:00.000Z`).\n\nFor more details see:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📚 Pagination guide](/docs/accessing-transactional-data#pagination)\n- [📖 Transaction model](/docs/the-transaction-model)\n- [📖 Transaction webhooks](/docs/reference-webhooks#transaction)","parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"name":"start","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-01-01T12:00:00.000Z"},{"name":"end","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-02-01T12:00:00.000Z"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from an earlier query","example":"abc123"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"cursor":{"type":"object","properties":{"next":{"type":"string","description":"The cursor to get the next results"}}}}},"examples":{"unenriched":{"summary":"Unenriched","description":"Raw transactions, like what you would get from the bank.","value":{"success":true,"cursor":{"next":"abc123"},"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS"}]}},"enriched":{"summary":"Enriched","description":"Transactions that have been enriched by Akahu.","value":{"success":true,"cursor":{"next":"abc123"},"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS","merchant":{"_id":"merchant_1111111111111111111111111","name":"Bob's Pizza"},"category":{"_id":"nzfcc_1111111111111111111111111","name":"Cafes and restaurants","groups":{"personal_finance":{"_id":"group_clasr0ysw0011hk4m6hlk9fq0","name":"Lifestyle"}}}}]}}}}}},"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"}}}},"/accounts/{id}/transactions/pending":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Account ID","example":"acc_1111111111111111111111111","schema":{"type":"string"}}],"get":{"tags":["Transactions"],"summary":"Get pending transactions by account","security":[{"user_token":[]}],"description":"Get a list of the user's pending transactions for a specific connected account.\n\nPending transactions are not stable (eg. the date or description may change) due to the unreliable nature of the underlying NZ bank data.\n\n>️ ℹ️ You can tell when we last fetched a transaction by looking at it's `updated_at` key.\n\n- All transactions timestamps are in **UTC**.\n\nFor more details see:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📚 Pending transactions guide](/docs/accessing-transactional-data#pending-transactions)\n- [📖 Transaction model](/docs/the-transaction-model)","parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingTransaction"}}}}}}},"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"}}}},"/transactions/ids":{"post":{"tags":["Transactions"],"summary":"Get transactions by IDs","security":[{"user_token":[]}],"description":"Gets a list of the user's transactions that match the provided list of Akahu transaction identifiers.\n\nThe intended use for this endpoint is to assist in [📖 transaction webhooks](/docs/reference-webhooks#transaction).\nWhen a webhook arrives it contains a list of changed transaction identifiers, which you can simply pass unchanged to this endpoint to retrieve the full transactions.\n\nThis endpoint is unusual, in that it is really a `GET`, dressed up as a `POST`.\nThe reason we do this is to avoid having to put all of the IDs in query parameters, which could potentially come up against maximum URL length constraints.\n\n- Transactions will look different depending on your app's permissions.\n- All times on the transaction are in **UTC**.\n\nFor more details see:\n- [📚 Accessing transactional data guide](/docs/accessing-transactional-data)\n- [📖 Transaction model](/docs/the-transaction-model)\n- [📖 Transaction webhooks](/docs/reference-webhooks#transaction)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string","description":"Transaction IDS"}},"example":["trans_1111111111111111111111111","trans_2222222222222222222222222"]}}},"parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"$ref":"#/components/parameters/ContentType"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}},"examples":{"unenriched":{"summary":"Unenriched","description":"Raw transactions, like what you would get from the bank.","value":{"success":true,"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS"}]}},"enriched":{"summary":"Enriched","description":"Transactions that have been enriched by Akahu.","value":{"success":true,"items":[{"_id":"trans_1111111111111111111111111","_account":"acc_1111111111111111111111111","_connection":"conn_1111111111111111111111111","created_at":"2020-01-01T01:00:00.000Z","updated_at":"2020-01-01T01:00:00.000Z","date":"2020-01-01T00:00:00.000Z","description":"{RAW TRANSACTION DESCRIPTION}","amount":-5.5,"balance":100,"type":"EFTPOS","merchant":{"_id":"merchant_1111111111111111111111111","name":"Bob's Pizza"},"category":{"_id":"nzfcc_1111111111111111111111111","name":"Cafes and restaurants","groups":{"personal_finance":{"_id":"group_clasr0ysw0011hk4m6hlk9fq0","name":"Lifestyle"}}}}]}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/me":{"get":{"tags":["Me"],"summary":"Get current user","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"description":"Get information about the Akahu user and the access they have provided.\n\n> ℹ️\n>\n> The `email` key will only be visible if you have the required permissions.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"$ref":"#/components/schemas/Me"}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Get all webhooks","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"description":"Gets the active webhook subscriptions that your app has created for the user.\n\nFor more details about webhooks see:\n  - [📖 Webhooks reference](/docs/reference-webhooks)\n  - [📖 Webhooks events](/reference-webhooks#token)","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}},"post":{"tags":["Webhooks"],"summary":"Subscribe to webhook","security":[{"user_token":[]}],"description":"> ℹ️\n>\n> Akahu's webhooks are unusual in that they need to be initialised **per user**, requiring a new webhook subscription for each event type you wish to receive for each user.\n\nRegister a new webhook subscription for the user, allowing your application to receive events on the following webhook types:\n\n  - `TOKEN`\n  - `ACCOUNT`\n  - `TRANSACTION`\n  - `PAYMENT`\n  - `TRANSFER`\n\n> ℹ️\n>\n> It is a good idea to use the `state` field to store a unique identifier related to your end user, allowing you to determine on an arrival of a webhook event which user of your application needs to be updated or notified.\n\n\nFor more details about webhooks see:\n  - [📖 Webhooks reference](/docs/reference-webhooks)\n  - [📖 Webhooks events](/reference-webhooks#token)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_type":{"type":"string","description":"Which types of events you want to receive webhooks for."},"state":{"type":"string","description":"State that will be returned with the webhook payload."}}},"examples":{"Token Webhook":{"summary":"Token Webhook","value":{"webhook_type":"TOKEN","state":"foobarbaz"}},"Account Webhook":{"summary":"Account Webhook","value":{"webhook_type":"ACCOUNT","state":"foobarbaz"}},"Transaction Webhook":{"summary":"Transaction Webhook","value":{"webhook_type":"TRANSACTION","state":"foobarbaz"}},"Payment Webhook":{"summary":"Payment Webhook","value":{"webhook_type":"PAYMENT","state":"foobarbaz"}}}}}},"parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"$ref":"#/components/parameters/ContentType"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"item_id":{"type":"string","description":"Newly created Akahu webhook identifer.","example":"hook_1111111111111111111111111"}}}}}},"400":{"description":"Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"examples":{"invalid_type":{"summary":"Invalid Webhook Type","description":"The specified webhook type doesn't exist.","value":{"success":false,"message":"Invalid webhook_type"}},"app_missing_destination":{"summary":"App Not Setup","description":"Your app has not been setup with a webhook destination URL.","value":{"success":false,"message":"App is missing webhook url"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/keys/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu webhook signing key ID","schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"summary":"Get public key","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGet one of the public keys that Akahu uses to sign webhooks.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"item":{"type":"string"}}},"example":{"success":true,"item":"-----BEGIN RSA PUBLIC KEY-----\\n { PEM ENCODED PUBLIC KEY } \\n-----END RSA PUBLIC KEY-----"}}}},"400":{"description":"Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"examples":{"expired":{"summary":"Key Expired","description":"This key has expired and should no longer be used.","value":{"success":false,"message":"This key has expired"}}}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"An Akahu Webhook ID","example":"hook_1111111111111111111111111","schema":{"type":"string"}}],"delete":{"tags":["Webhooks"],"summary":"Unsubscribe from webhook","description":"Delete a webhook subscription that your application has previously created for the user.\n\nFor more details about webhooks see:\n  - [📖 Webhooks reference](/docs/reference-webhooks)\n  - [📖 Webhooks events](/reference-webhooks#token)","security":[{"user_token":[]}],"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"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"}}}},"/webhook-events":{"get":{"tags":["Webhooks"],"summary":"Get webhook events","security":[{"app_auth":[]}],"description":"> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nReturns a list of webhook events that have been published to your application by Akahu within the `start` and `end` time range.\n\n>️ ℹ️ Time range defaults to the last 30 days.\n\nFor more details about webhooks see:\n  - [📖 Webhooks reference](/docs/reference-webhooks)\n  - [📖 Webhooks events](/reference-webhooks#token)","parameters":[{"$ref":"#/components/parameters/xAkahuId"},{"name":"status","in":"query","schema":{"type":"string","example":"SENT","enum":["SENT","FAILED","RETRY"]},"description":"State of the webhook event"},{"name":"start","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-01-01T12:00:00.000Z"},{"name":"end","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 formatted date","example":"2021-02-01T12:00:00.000Z"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/support/{transaction_id}":{"parameters":[{"name":"transaction_id","in":"path","required":true,"description":"An Akahu Transaction ID","schema":{"type":"string"}}],"post":{"tags":["Support"],"summary":"Transaction support","security":[{"user_token":[]}],"description":"Let us know when we get something wrong 🙏.\nThe request body should match the type of request you are making:\n\n### Notify Us Of A Duplicate ###\n\n| Parameter  | Example                             | Description                                                                            |\n|:-----------|:------------------------------------|:---------------------------------------------------------------------------------------|\n| `type`     | `\"DUPLICATE\"`                       | Let us know that two Akahu transactions are actually the same transaction in the bank. |\n| `other_id` | `\"trans_1111111111111111111111111\"` | The duplicate transaction ID.                                                          |\n\n### Notify Us Of An Enrichment Error ###\n\n| Parameter  | Example                              | Description                                           |\n|:-----------|:-------------------------------------|:------------------------------------------------------|\n| `type`     | `\"ENRICHMENT_ERROR\"`                 | Let us know when we get something wrong.              |\n| `fields`   | `[ \"merchant.name\"]`                 | A list of dot-separated paths to the incorrect values |\n| `comment`  | `\"X should be Y\"`                    | Additional info you want to include.                  |\n\n### Suggest An Improvement To Enrichment Data ###\n\n| Parameter  | Example                        | Description                                                                                           |\n|:-----------|:-------------------------------|:------------------------------------------------------------------------------------------------------|\n| `type`     | `\"ENRICHMENT_SUGGESTION\"`      | Let us know about further enrichment that can be applied to this transaction transaction in the bank. |\n| `comment`  | `\"Can you please add X to Y?\"` | The enrichment information you want to tell us about.                                                 |","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","example":"DUPLICATE","enum":["DUPLICATE","ENRICHMENT_ERROR","ENRICHMENT_SUGGESTION"],"description":"What type of support request you want to make:\n\n- `DUPLICATE` → Report duplicate transactions.\n\n- `ENRICHMENT_ERROR` → Enrichment is incorrect or contained unexpected data.\n\n- `ENRICHMENT_SUGGESTION` → Suggest an improvement on existing enrichment."},"other_id":{"type":"string","description":"In the case of duplicates, the duplicate transaction ID."},"fields":{"type":"array","description":"In the case of enrichment errors, the dot-separated paths to the incorrect values.","items":{"type":"string"}},"comment":{"type":"string","description":"A comment describing the problem and giving extra details."}}}}}},"parameters":[{"$ref":"#/components/parameters/xAkahuId"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}}}}