--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # Get transactions by IDs Gets a list of the user's transactions that match the provided list of Akahu transaction identifiers. The intended use for this endpoint is to assist in [📖 transaction webhooks](/docs/reference-webhooks#transaction). When 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. This endpoint is unusual, in that it is really a `GET`, dressed up as a `POST`. The 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. - Transactions will look different depending on your app's permissions. - All times on the transaction are in **UTC**. For more details see: - [📚 Accessing transactional data guide](/docs/accessing-transactional-data) - [📖 Transaction model](/docs/the-transaction-model) - [📖 Transaction webhooks](/docs/reference-webhooks#transaction) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Akahu Enduring API", "description": "This API is the primary way for apps to interact with a user's data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.akahu.io/v1" } ], "components": { "parameters": { "xAkahuId": { "name": "X-Akahu-Id", "in": "header", "required": true, "description": "Your **App ID Token**.", "schema": { "type": "string" }, "example": "{{app_token}}" }, "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." } }, "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" } } } } } }, "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": { "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" } } } } } } }, "tags": [ { "name": "Transactions" } ], "paths": { "/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" } } } } } } ```