---
title: "Get transactions by IDs"
method: POST
path: "/transactions/ids"
tags: ["Transactions"]
---

# Get transactions by IDs

`POST /transactions/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)

## Headers

- `X-Akahu-Id` string, required
- `Content-Type` string

## Request body

- string[]

## Response `200`

Successful response.

- object
  - `success` boolean
  - `items` Transaction[]
    - `_id` string, required — The unique identifier for this transaction
    - `_account` string, required — The Account ID to identify which account this transaction belongs to
    - `_connection` string, required — The Connection ID to identify which institution this transaction was retrieved from.
    - `date` string, date-time, required — The ISO 8601 timestamp of when this transaction was lodged by the bank
    - `description` string, required — The raw transaction description, essentially what you see on a bank statement
    - `type` 'CARD' | 'PAYMENT' | 'TRANSFER' | 'INTEREST' | 'FEE' | 'TAX' | 'DIRECT CREDIT' | 'DIRECT DEBIT' | 'STANDING ORDER' | 'ATM' | 'FX' | 'LOAN' | 'KIWISAVER' | 'CREDIT' | 'DEBIT' | 'UNKNOWN', required — The type of transaction: - `CARD` The transaction was initiated via Credit, Debit, or EFTPOS card. - `PAYMENT` An outbound payment to another New Zealand bank account. - `TRANSFER` A money transfer between two of the user's accounts with this provider. - `INTEREST` Interest received from a savings or investment account. - `FEE` Fee paid to the institution e.g. an account fee, card fee, ATM fee. - `TAX` Tax paid on interest or other source of income. - `DIRECT CREDIT` Payment received from another party. - `DIRECT DEBIT` Direct debit payment initiated by (and paid to) a third party with prior authorization from the account holder. - `STANDING ORDER` A regular scheduled payment, aka. 'Automatic payment'. - `ATM` ATM deposit or withdrawal. - `FX` Foreign currency exchange. - `LOAN` Payments towards a loan. - `KIWISAVER` Transactions towards a KiwiSaver account. - `CREDIT` A fallback for any other money that has entered the account. - `DEBIT` A fallback for any other money that has left the account. - `UNKNOWN` An unknown transaction type.
    - `amount` number, required — The amount of money being debited or credited by this transaction. A negative value represents a debit and positive value a credit.
    - `balance` number, nullable — The account balance after the receipt of this transaction, where available
    - `meta` object — 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**.
      - `conversion` object — Currency conversion information for payments that have been converted to a foreign currency. All fields are optional except `currency`.
        - `currency` string — The 3 digit currency code identifying the foreign currency involved in the conversion.
        - `amount` number — The amount of foreign currency involved in this transaction.
        - `rate` number — The currency conversion rate.
        - `fee` number — The amount of any currency conversion fee associated with the transaction.
      - `card` string — 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` string — 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` object
      - `category` object, required — 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.
        - `_id` string, required — The NZFCC Category ID
        - `name` string, required — The NZFCC Category Name
        - `components` object[]
          - `name` string — The category name
          - `type` string — The category set that this category comes from
        - `groups` object, required — Higher level groupings that this category belongs to.
      - `merchant` object — The merchant that the transaction is paying to.
        - `_id` string, required — The Akahu Merchant ID
        - `name` string, required — The merchant name
        - `logo` string, url — URL of a .png image of the merchant logo. If no logo is available, a placeholder image is provided.
        - `website` string, uri — The Akahu Merchant website
      - `confidence` number, required — 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.

## Other responses

- `400` — Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.
- `401` — You are not authorised to access this content.
- `403` — You are not allowed to access this content.
- `500` — An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.

---

[API](https://skmtc.net/akahu/apis/akahu-enduring-api.md) · [All operations](https://skmtc.net/akahu/apis/akahu-enduring-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/akahu/akahu-enduring-api/versions/b2de9915920d/schema)