---
title: "Enrich a batch of transactions"
method: POST
path: "/search"
tags: ["Transaction Enrichment"]
---

# Enrich a batch of transactions

`POST /search`

Enrich a batch of transactions using Genie.

## Request body

- GenieSearchQueryItem[]
  - `id` string — A unique correlation ID for the query to help you to find the corresponding result in the response data.
  - `description` string — The transaction description. This should be the full description as provided by the bank / transaction source.
  - `_connection` 'conn_cjgaawozb000001nyd111xixr' | 'conn_cjgaaqcna000001ldwof8tvj0' | 'conn_cjgaatd57000001pe1t1z0iy9' | 'conn_ck5rhsdbv0000ftx1bmdu9zas' | 'conn_cjgaac5at000001qi2yw8ftil' | 'conn_ckydkmy3r000009mde2sx2i4d' | 'conn_cjgab1c8e000001pmyxrkhova' | 'conn_cjgab6fis000001qsytf1semy' | 'conn_cjgaaozdo000001mrnqmkl1m0' — The Akahu connection identifier corresponding to the bank from which the transaction description was sourced. It is strongly recommended to include this parameter to ensure best results. The following connection identifiers are available: - ANZ: `conn_cjgaawozb000001nyd111xixr` - ASB: `conn_cjgaaqcna000001ldwof8tvj0` - BNZ: `conn_cjgaatd57000001pe1t1z0iy9` - Heartland: `conn_ck5rhsdbv0000ftx1bmdu9zas` - Kiwibank: `conn_cjgaac5at000001qi2yw8ftil` - Rabobank: `conn_ckydkmy3r000009mde2sx2i4d` - The Cooperative Bank: `conn_cjgab1c8e000001pmyxrkhova` - TSB: `conn_cjgab6fis000001qsytf1semy` - Westpac: `conn_cjgaaozdo000001mrnqmkl1m0`
  - `amount` number — Transaction amount (+ for credit, - for debit).
  - `direction` 'DEBIT' | 'CREDIT' — Whether the transaction is a debit or credit.
  - `type` 'CARD' | 'DIRECT DEBIT' | 'PAYMENT' | 'STANDING ORDER' — The type of transaction this query relates to.
  - `meta` object
    - `other_account` string — The payee bank account number.
    - `merchant_name` string — The merchant's name. If provided alongside `merchant_city` and `merchant_country`, these values will be used as additional data points for enrichment.
    - `merchant_city` string — The merchant's city.
    - `merchant_country` string — The merchant's country.

## Response `200`

Success

- GenieSearchResponse
  - `success` true, required
  - `items` GenieSearchQueryResult[], required
    - `id` string — The correlation identifier for the query (if you provided one).
    - `query` string, required — The original query description as provided.
    - `results` object[], required — The enrichment result for this query. Will contain 1 item if enrichment is successful, otherwise the array will be empty.
      - `confidence` number, required — A value between 0 and 0.99 (inclusive) indicating the strength of the matched result (currently the lowest returned confidence score is 0.5).
      - `match_algorithm` string, required — An opaque value that identifies the algorithm that generated this enrichment result. This can be used in combination with webhooks to invalidate cached results when algorithms are added or updated by Akahu.
      - `match_reference` string, required — An opaque value that identifies the specific enrichment rule or matching logic that generated this result. This can be used in combination with webhooks to invalidate cached results when enrichment rules are updated by Akahu.
      - `category` GenieCategory, required — A category classification result from Genie. This classification provides the base [NZFCC](https://nzfcc.org) category code for the transaction. Additionally, the `groups` attribute includes a mapping of the NZFCC category into broader (less-specific) category groups. Category grouping is based on mappings which are able to be customised per-client. The `personal_finance` mapping is included by default.
        - `_id` string, required — The [NZFCC](https://nzfcc.org) category code for the transaction
        - `name` string, required — The name of the NZFCC category for this transaction
        - `groups` object, required — A dictionary of category groups, keyed by category mapping name, for the NZFCC base category.
      - `merchant` GenieMerchant — A merchant match result from Genie.
        - `_id` string, required — The unique merchant identifier.
        - `name` string, required — The merchant's name (trading name).
        - `logo` string, required — A URL referencing the merchant's logo. If no logo is available, a placeholder image is provided.
        - `logo_is_placeholder` boolean — A boolean flag, set to `true` if the `logo` URL points to a placeholder image rather than the merchant's real logo (i.e. there is no logo available for this merchant). This flag may be useful if you would prefer not to display placeholder logos or replace them with your own.
        - `website` string — The URL for the merchant's website.
        - `phone` string — The merchant's phone number.
        - `nzbn` string — The merchant's NZBN (New Zealand Business Number).
        - `location` GenieLocation — A physical location.
          - `accuracy` 'country' | 'region' | 'locality' | 'sublocality' | 'establishment', required
          - `formatted` string, required
          - `coordinates` GenieCoordinates, required — Latitude/longitude location coordinates.
            - `lat` number, required
            - `lon` number, required
          - `address` GenieAddress
            - `street` string, required
            - `suburb` string
            - `city` string, required
            - `region` string, required
            - `country` string, required
            - `postal_code` string, required
        - `tags` GenieTag[] — Tags that apply to the merchant. For example, to indicate that the merchant provides a subscription service.
      - `outlet` GenieOutlet — An individual outlet (i.e. specific location). An outlet will always be returned in combination with its related "parent" merchant.
        - `_id` string, required — The unique outlet identifier.
        - `name` string, required — The outlet name. This is usually more specific than the merchant name. For example, the merchant name may be "Pak'nSAVE", while the outlet name is "Pak'nSAVE Sylvia Park".
        - `logo` string — A URL referencing the outlet's logo. This field will only be included if the logo for this outlet differs from the merchant's logo.
        - `website` string — The URL for the outlet's website. This field will only be included if the website for this outlet differs from the merchant's website.
        - `phone` string — The outlet's phone number. This field will only be included if the phone number for this outlet differs from the merchant's phone number.
        - `nzbn` string — The outlet's NZBN (New Zealand Business Number). This field will only be included if the NZBN for this outlet differs from the merchant's NZBN.
        - `location` GenieLocation — A physical location.
          - `accuracy` 'country' | 'region' | 'locality' | 'sublocality' | 'establishment', required
          - `formatted` string, required
          - `coordinates` GenieCoordinates, required — Latitude/longitude location coordinates.
            - `lat` number, required
            - `lon` number, required
          - `address` GenieAddress
            - `street` string, required
            - `suburb` string
            - `city` string, required
            - `region` string, required
            - `country` string, required
            - `postal_code` string, required
        - `tags` GenieTag[] — Tags that apply to the outlet. For example, to indicate that the outlet provides a subscription service. Tags are inherited (and potentially extended) from the outlet's "parent" merchant.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Rate Limiting
- `500` — Internal Server Error

---

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