{"openapi":"3.1.0","info":{"title":"Akahu One-Off REST API","description":"Retrieve a one-off snapshot of a user's account data","version":"1.0.0"},"servers":[{"url":"https://api.oneoff.akahu.io/v1"}],"components":{"parameters":{"Code":{"name":"code","in":"path","required":true,"description":"The one-off authorization code, provided to your application by redirection to your `redirect_uri` upon the user's successful completion of the authorization flow.","example":"id_1111111111111111111111111","schema":{"type":"string"}},"ContentType":{"name":"Content-Type","in":"header","schema":{"type":"string"},"example":"application/json"}},"securitySchemes":{"app_auth":{"type":"http","scheme":"basic","description":"HTTP 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 must be included in all requests to the one-off API."}},"responses":{"400":{"description":"Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid Content-Type"}}}}}},"401":{"description":"You are not authorised to access this content.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Permission Denied"}}}}}},"403":{"description":"You are not allowed to access this content.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Forbidden"}}}}}},"404":{"description":"The item you are trying to access doesn't exist.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Not Found"}}}}}},"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":{"Status":{"type":"object","required":["connection","status","available_results","expires_at","created_at"],"properties":{"connection":{"type":"object","description":"Information about institution that the user connected their accounts from (eg. ANZ bank).","required":["_id","name","logo"],"properties":{"_id":{"type":"string","description":"A unique identifier for this institution, prefixed by `conn_`.","example":"conn_cjgaawozb000001nyd111xixr"},"name":{"type":"string","description":"The name of the institution.","example":"ANZ"},"logo":{"type":"string","format":"uri","description":"A URL pointing to a .png image of the institution's logo.","example":"https://cdn.akahu.nz/logos/connections/conn_cjgaawozb000001nyd111xixr"}}},"status":{"type":"string","enum":["PROCESSING","COMPLETE","ERROR"],"example":"COMPLETE","description":"The status of the one-off data retrieval process:\n\n- `PROCESSING` → Akahu is still processing the result. Expect the status to shortly progress to either `COMPLETE` or `ERROR`.\n- `COMPLETE` → Akahu has finished processing the result and it is available for your application to retrieve.\n- `ERROR` → There was an error that meant the result could not be processed. See `status_reason` for more detail."},"status_reason":{"type":"string","enum":["TIMEOUT","PROCESSING_ERROR"],"example":"PROCESSING_ERROR"},"available_results":{"type":"object","description":"A collection of boolean flags to indicate which results are available for fetching.\n\nWhile the result has a status of `PROCESSING`, these flags will be updated as data becomes available. This allows your application to fetch data and provide progress feedback to the user as quickly as possible.\n\nIn general, `accounts`, `parties`, and `pdfs` results will be available almost immediately. Transactions undergo additional asynchronous processing, so may take a few seconds to become available.\n\nOnce the result is assigned the `COMPLETE` state, these flags will no longer change.","properties":{"accounts":{"type":"boolean","example":true,"description":"Account data is available to be fetched"},"parties":{"type":"boolean","example":true,"description":"Party data is available to be fetched"},"transactions":{"type":"boolean","example":true,"description":"Transaction data is available to be fetched"},"pdfs":{"type":"boolean","example":true,"description":"PDF files are available to be fetched"}}},"available_accounts_count":{"type":"integer","example":5,"deprecated":true,"description":"**Deprecated**\n\nThis field is not available for official open banking connections.\n\nThe total number of accounts that were available for the user to share with your application. They may have chosen a subset of these to share, which will be available from the [`GET /accounts/{code}`](/reference/get_accounts-code) endpoint."},"expires_at":{"type":"string","format":"date-time","description":"When this result expires. After expiry it will no longer be accessible. Formatted as an ISO 8601 timestamp."},"created_at":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."}}},"Account":{"type":"object","required":["_id","_connection","name","formatted_account","type","attributes","balance","meta"],"properties":{"_id":{"type":"string","description":"A unique identifier for the account in the Akahu system. It is always be prefixed by `oneoff_acc_` so that you can tell that it belongs to an account.","example":"oneoff_acc_1111111111111111111111111"},"_connection":{"type":"string","description":"Connection ID identifying the institution the account has been connected from.","example":"conn_cjgaawozb000001nyd111xixr"},"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"},"balance":{"type":"object","description":"The account balance","required":["current"],"properties":{"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}}},"type":{"type":"string","example":"DEPOSITORY","enum":["DEPOSITORY","CREDIT CARD","LOAN"],"description":"The account type.\n\n- `DEPOSITORY` → A regular transactional or savings bank account.\n- `CREDIT CARD` → A credit card.\n- `LOAN` → A loan account (includes line-of-credit accounts such as revolving home loans).\n\n> ℹ️ Note that currently only the listed account types are supported for retrieval via the Akahu one-off API. Additional account types (such as investment and Kiwisaver accounts) may be added at a later date."},"attributes":{"type":"array","description":"Indicates what functionality the account has.\n- `TRANSACTIONS` → This account can provide transaction data.\n- `TRANSACTION_EXPORTS` → This account can provide transaction data in PDF format.\n- `STATEMENTS` → This account can provide official PDF statements.","items":{"type":"string","enum":["TRANSACTIONS","TRANSACTION_EXPORTS","STATEMENTS"],"example":"TRANSACTIONS"}},"formatted_account":{"type":"string","description":"For bank accounts, this will contain the account number in the standardised format `00-0000-0000000-00`. For non bank accounts (credit cards and some loans), the account number format provided by the bank will be passed through.","example":"12-1234-1234567-12"},"meta":{"type":"object","description":"Metadata regarding this account","properties":{"holder":{"type":"string","description":"The account holder name as provided by the bank","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},"nickname":{"type":"string","description":"The account nickname","example":"Sam's Savings"},"product_name":{"type":"string","description":"The account product name as provided by the bank","example":"Super Saver"},"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"]}}}}},"PartyNameComponents":{"type":"object","description":"A party's name components. All components are optional as format depends on how the data is provided by the bank.","properties":{"prefix":{"type":"string","description":"The party's prefix, e.g. Mr","example":"Mr"},"initials":{"type":"string","description":"The party's initials (Excluding surname), e.g. RJJ for 'Robert John Joseph Smith'","example":"RJJ"},"preferred_name":{"type":"string","description":"The party's preferred name, if they have specified this at their bank e.g. Bob instead of Robert","example":"Bob"},"given_name":{"type":"string","description":"The party's given name, e.g. Robert","example":"Robert"},"middle_name":{"type":"string","description":"The party's middle name(s), if any, e.g. John Joseph","example":"John Joseph"},"surname":{"type":"string","description":"The party's surname","example":"Smith"}}},"PartyName":{"type":"object","description":"A party's name if available. Your app must have the `IDENTITY_NAMES` scope, otherwise this field will be undefined.","properties":{"value":{"type":"string","description":"The full name string as provided by the financial institution.","example":"MR ROBERT JOHN JOSEPH SMITH"},"components":{"$ref":"#/components/schemas/PartyNameComponents"}},"required":["value"]},"PartyEmailAddress":{"type":"object","description":"A party's email address","properties":{"subtype":{"type":"string","description":"The email address type.\n\n- `PRIMARY` → The party's primary email address.\n- `SECONDARY` → The party's secondary email address.","enum":["PRIMARY","SECONDARY"]},"value":{"type":"string","description":"The email address string as provided by the financial institution.","example":"hello@akahu.nz"},"verified":{"type":"boolean","description":"Whether the email address has been verified by the financial institution.","example":true}},"required":["subtype","value","verified"]},"PartyPhoneNumber":{"type":"object","description":"A party's phone number","properties":{"subtype":{"type":"string","description":"The phone number type.\n\n- `MOBILE` → The party's mobile phone number.\n- `HOME` → The party's home phone number.\n- `WORK` → The party's work phone number.","enum":["MOBILE","HOME","WORK"]},"value":{"type":"string","description":"The phone number string as provided by the financial institution.","example":"+64271234567"},"verified":{"type":"boolean","description":"Whether the phone number has been verified by the financial institution.","example":true}},"required":["subtype","value","verified"]},"PartyAddress":{"type":"object","description":"A party's address","properties":{"subtype":{"type":"string","description":"The address type.\n\n- `RESIDENTIAL` → Where the party lives.\n- `POSTAL` → Where the party receives their postage. (May be the same as the residential address)","enum":["RESIDENTIAL","POSTAL"]},"value":{"type":"string","description":"The raw address string as provided by the financial institution.","example":"999 QUEEN STREET, AUCKLAND CBD, AUCKLAND, 1010, NEW ZEALAND"},"formatted":{"type":"string","description":"The address having been parsed and formatted uniformly by Akahu","example":"999 Queen Street, Auckland CBD, Auckland 1010, New Zealand"},"components":{"type":"object","description":"The parsed address components","properties":{"street":{"type":"string","description":"The address's street number and name"},"suburb":{"type":"string","description":"The address's suburb"},"city":{"type":"string","description":"The address's city"},"region":{"type":"string","description":"The address's region"},"postal_code":{"type":"string","description":"The address's postal code"},"country":{"type":"string","description":"The address's country"}}},"google_maps_place_id":{"type":"string","description":"The Place ID for the address if using the Google Maps APIs"}},"required":["subtype","value"]},"Party":{"type":"object","description":"Identity data related to the registered party at the financial institution that the user has shared their data from. This data is sourced from the profile information at the connected institution rather than any specific account held within.","properties":{"name":{"$ref":"#/components/schemas/PartyName"},"dob":{"type":"string","description":"The party's date of birth (yyyy-mm-dd) if available. Your app must have the `IDENTITY_DOBS` scope, otherwise this field will be undefined."},"tax_number":{"type":"string","description":"The party's tax number if available. Your app must have the `IDENTITY_TAX_NUMBERS` scope, otherwise this field will be undefined."},"pir":{"type":"number","description":"The party's Prescribed Investor Rate (PIR) if available. Your app must have the `IDENTITY_TAX_NUMBERS` scope, otherwise this field will be undefined."},"email_addresses":{"type":"array","description":"The party's email addresses. Your app must have the `IDENTITY_EMAILS` scope, otherwise an empty array will be returned.","items":{"$ref":"#/components/schemas/PartyEmailAddress"}},"phone_numbers":{"type":"array","description":"The party's phone numbers. Your app must have the `IDENTITY_PHONES` scope, otherwise an empty array will be returned.","items":{"$ref":"#/components/schemas/PartyPhoneNumber"}},"addresses":{"type":"array","description":"The party's addresses. Your app must have the `IDENTITY_ADDRESSES` scope, otherwise an empty array will be returned.","items":{"$ref":"#/components/schemas/PartyAddress"}}},"required":["email_addresses","phone_numbers","addresses"]},"TransactionType":{"type":"string","example":"EFTPOS","enum":["CARD","PAYMENT","TRANSFER","INTEREST","FEE","TAX","DIRECT CREDIT","DIRECT DEBIT","STANDING ORDER","ATM","FX","LOAN","KIWISAVER","CREDIT","DEBIT","UNKNOWN"],"description":"Type of the transaction:\n\n  - `CARD` → The transaction was initiated via Credit, Debit, or EFTPOS card.\n  - `PAYMENT` → An outbound payment to another New Zealand bank account.\n  - `TRANSFER` → An internal money transfer between two accounts.\n  - `INTEREST` → Credits: Interest received from a savings or investment account. Debits: Interest charged on a debt (such as a loan, credit card, or overdraft).\n  - `FEE` → Fee paid to the institution e.g. an account fee, card fee, ATM fee.\n  - `TAX` → Tax paid on interest or other source of income.\n  - `DIRECT CREDIT` → Payment received from another party.\n  - `DIRECT DEBIT` → Direct debit payment initiated by (and paid to) a third party with prior authorization from the account holder.\n  - `STANDING ORDER` → Automatic payment.\n  - `ATM` → ATM deposit or withdrawal.\n  - `FX` → Foreign currency exchange.\n  - `LOAN` → Payments towards a loan.\n  - `KIWISAVER` → Transactions towards a KiwiSaver account.\n  - `CREDIT` → Money has entered the account (fallback).\n  - `DEBIT` → Money has left the account (fallback)."},"Transaction":{"type":"object","required":["_id","_account","_connection","date","description","type","amount"],"properties":{"_id":{"type":"string","description":"The unique identifier for this transaction","example":"oneoff_trans_1111111111111111111111111"},"_account":{"type":"string","description":"The Account ID to identify which account this transaction belongs to","example":"oneoff_acc_1111111111111111111111111"},"_connection":{"type":"string","description":"The Connection ID to identify which institution this transaction was retrieved from.","example":"conn_1111111111111111111111111"},"date":{"type":"string","format":"date-time","description":"The ISO 8601 timestamp of when this transaction was lodged 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"},"type":{"$ref":"#/components/schemas/TransactionType"},"amount":{"type":"number","description":"The amount of money being debited or credited by this transaction. A negative value represents a debit and positive value a credit.","example":-5.5},"balance":{"type":["number","null"],"description":"The account balance after the receipt of this transaction, where available","example":100},"meta":{"type":"object","description":"Additional metadata that Akahu has extracted from the transaction. Availability of this metadata varies greatly depending on the institution that the transaction was sourced from and the transaction type. Please note that **all metadata items are optional**.","properties":{"conversion":{"type":"object","description":"Currency conversion information for payments that have been converted to a foreign currency. All fields are optional except `currency`.","properties":{"currency":{"type":"string","description":"The 3 digit currency code identifying the foreign currency involved in the conversion."},"amount":{"type":"number","description":"The amount of foreign currency involved in this transaction."},"rate":{"type":"number","description":"The currency conversion rate."},"fee":{"type":"number","description":"The amount of any currency conversion fee associated with the transaction."}}},"card":{"type":"string","description":"Partial card number associated with this transaction. This is generally the last 4 digits and may relate to a debit, credit, or EFTPOS card."},"other_account":{"type":"string","description":"If the transaction involves money transfer to/from another New Zealand bank account, this field may contain the account number associated with the other account. Transactions that may have this data available include: `PAYMENT`, `TRANSFER`, `STANDING ORDER`, `DIRECT DEBIT`, `DIRECT CREDIT`."}}},"enrichment":{"type":"object","required":["category","confidence"],"properties":{"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.","required":["_id","name","groups"],"properties":{"_id":{"type":"string","description":"The NZFCC Category ID","example":"nzfcc_1111111111111111111111111"},"name":{"type":"string","description":"The NZFCC Category Name","example":"Cafes & Restaurants"},"components":{"type":"array","deprecated":true,"items":{"type":"object","description":"A category that this transaction falls under","properties":{"name":{"type":"string","description":"The category name","example":"Food"},"type":{"type":"string","description":"The category set that this category comes from","example":"nzfcc:pfm"}}},"example":[{"name":"Fast food restaurants","type":"nzfcc:base"},{"name":"Cafes & Restaurants","type":"nzfcc:group"},{"name":"Lifestyle","type":"nzfcc:pfm"}]},"groups":{"type":"object","description":"Higher level groupings that this category belongs to.","additionalProperties":{"type":"object","required":["_id","name"],"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"}}}}},"merchant":{"type":"object","description":"The merchant that the transaction is paying to.","required":["_id","name"],"properties":{"_id":{"type":"string","description":"The Akahu Merchant ID","example":"merchant_cm6pib1l5000i08lhfah11sht"},"name":{"type":"string","description":"The merchant name","example":"Bob's Pizza"},"logo":{"type":"string","format":"url","description":"URL of a .png image of the merchant logo. If no logo is available, a placeholder image is provided.","example":"https://cdn.akahu.nz/logos/merchants/merchant_cm6pib1l5000i08lhfah11sht"},"website":{"type":"string","format":"uri","description":"The Akahu Merchant website","example":"https://pizza.bob.nz"}}},"confidence":{"type":"number","description":"A score between `0` and `0.99` indicating Akahu's confidence in the enrichment accuracy. Currently the lowest returned confidence score is `0.5`. We are still tweaking the maths behind this score, but intend to release guidelines for usage once it becomes stable."}}}}},"PdfExport":{"type":"object","properties":{"_account":{"type":"string","description":"The Account ID for which this export was produced.","example":"oneoff_acc_1111111111111111111111111"},"description":{"type":"string","description":"If available, how this document is described by the bank.","example":"2022-Jan-01_Personal"},"meta":{"type":"object","description":"Additional metadata concerning this document.","additionalProperties":true},"period":{"type":"object","description":"The period that this PDF export covers.","properties":{"start":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."},"end":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."}}},"uri":{"type":"string","description":"A short-lived URI that can be used to access the PDF file retrieved from the bank. Each request to this endpoint generates a new URI with a new expiry."},"expires_at":{"type":"string","description":"When the PDF URI expires. Each request to this endpoint generates a new URI with a new expiry. After expiry this URI will no longer be accessible. Formatted as an ISO 8601 timestamp.","format":"date-time"}}},"PdfStatement":{"type":"object","properties":{"_accounts":{"type":"array","description":"The Account IDs described by this statement. In most cases this will only be one account, but in the case of Kiwibank, one statement is produced per account holder.","items":{"type":"string","example":"oneoff_acc_1111111111111111111111111"}},"description":{"type":"string","description":"If available, how this document is described by the bank.","example":"2022-Jan-01_Personal"},"meta":{"type":"object","description":"Additional metadata concerning this document.","additionalProperties":true},"period":{"type":"object","description":"The period that this PDF covers.","properties":{"start":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."},"end":{"type":"string","format":"date-time","description":"Formatted as an ISO 8601 timestamp."}}},"uri":{"type":"string","description":"A short-lived URI that can be used to access the PDF file retrieved from the bank. Each request to this endpoint generates a new URI with a new expiry."},"expires_at":{"type":"string","description":"When the PDF URI expires. Each request to this endpoint generates a new URI with a new expiry. After expiry this URI will no longer be accessible. Formatted as an ISO 8601 timestamp.","format":"date-time"}}},"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":{"given_name":{"type":"string"},"middle_name":{"type":"string"},"family_name":{"type":"string"},"initials":{"type":"array","items":{"type":"string"}},"prefix":{"type":"string"}},"description":"The Party name 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","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}}},"VerifyNameHolderSource":{"type":"object","properties":{"type":{"type":"string","enum":["HOLDER_NAME"],"description":"The name was matched against an Account Holder"},"meta":{"type":"object","description":"The Account data that this name was verified against","properties":{"bank":{"type":"string","description":"Display name of the bank","example":"Kiwibank"},"account_number":{"type":"string","description":"Unique bank account identifier","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}}},"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}}},"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"]}]}}},"tags":[{"name":"Status"},{"name":"Accounts"},{"name":"Parties"},{"name":"Transactions"},{"name":"PDFs"}],"paths":{"/status/{code}":{"get":{"tags":["Status"],"summary":"Get Result Status","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"description":"Get the current status of the one-off data retrieval process.\n\nYour application should poll this endpoint to check the status of the result processing before fetching data from other endpoints. Use the `available_results` flags to know when each type of result is available for your application to fetch.\n\nOnce the returned `status` becomes `COMPLETE` or `ERROR`, the result will no longer be updated and your application can stop polling.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Status"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/accounts/{code}":{"get":{"tags":["Accounts"],"summary":"Get Accounts","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"description":"Get a list of the accounts that the user has shared with your application.\n\n> ℹ️\n>\n> The format for the returned account depends on the permissions you have!\n\n> ℹ️\n>\n> The **one-off** API account schema is similar, but not identical to the **enduring** API account schema. In particular, note the differences in account `type`.","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"}}}},"/parties/{code}":{"get":{"tags":["Parties"],"summary":"Get Parties","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"description":"Get identity data related to the registered party at the institution that the user has shared data from. This data is sourced from the profile information at the connected institution rather than any specific account held within.\n\nIn general this identity data will relate to the person who has connected the account, however if the user connects an account that is registered under another party (e.g. another person, an LLC, a trust), the result may also contain data pertaining to these other parties. That is to say, Akahu is simply passing this information on from the institution.\n\n> ℹ️\n>\n> This endpoint returns an array of items for consistency with the parties response from our enduring account connectivity API. However, because each one-off account connection flow relates to only a single session at a single institution, this endpoint will only ever return at-most one party item.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"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"}}}},"/transactions/{code}":{"get":{"tags":["Transactions"],"summary":"Get Transactions","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor to fetch the next page - found in the response of a previous query.","example":"eJyrVipITE9VsjKsBQASqQNF"}],"description":"Get a list of the user's transactions from the accounts that they have shared with your application.\n\nTransactions are returned in descending date order in [🔗 pages](/docs/accessing-transactional-data#pagination) of up to 500 items. The time period for which transactions are retrieved can be configured for your application up to a maximum of 2 years of historic data.\n\nAll transaction timestamps are in **UTC**.\n\n> ℹ️\n>\n> The **one-off** API transaction schema is similar, but not identical to the **enduring** API transaction schema. In particular, note the differences in the available values for `type`, and the enrichment results `category`, `merchant`, and `confidence` which are nested under the `enrichment` key.","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"}}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/pdfs/exports/{code}":{"get":{"tags":["PDFs"],"summary":"Get PDF Transaction Exports","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"description":"Get a list of PDF transaction exports for accounts that the user has shared with your application.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PdfExport"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/pdfs/statements/{code}":{"get":{"tags":["PDFs"],"summary":"Get PDF Statements","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"description":"Get a list of PDF statements for accounts that the user has shared with your application.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PdfStatement"}}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"500":{"$ref":"#/components/responses/500"}}}},"/identity/{code}/verify/name":{"post":{"tags":["Identity"],"summary":"Verify your user's 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\nFor more details about the data returned, see:\n  - [📚 One-Off Verify Name](/docs/oneoff-verify-name)","security":[{"app_auth":[]}],"parameters":[{"$ref":"#/components/parameters/Code"},{"$ref":"#/components/parameters/ContentType"}],"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"}}}}}}