Akahu Feedback API

openapi: 3.2.0
info:
  title: Genie transaction enrichment Feedback API
  version: 1.0.0
  description: 'Applications that use Akahu for bank account connectivity can use our transactions API to get high quality enriched transactions that include merchant and category information. We''ve built the Genie API to expose Akahu''s transaction enrichment engine for applications that instead source raw transaction data themselves.


    Genie is entirely separate from the core Akahu API and does not require an Akahu App ID Token or App Secret to access. If you''re keen to get your hands on an API key to try it out, get in touch with us at hello@akahu.nz.'
servers:
- url: https://api.genie.akahu.io/v1
tags:
- name: Feedback
paths:
  /feedback:
    post:
      tags:
      - Feedback
      summary: Submit enrichment feedback
      description: 'Submit feedback about enrichment results returned by Genie.


        Using this endpoint you can suggest corrections to an enrichment result or provide information for queries where Genie has not returned a result.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenieFeedback'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                required:
                - success
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '429':
          description: Rate Limiting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenieErrorResponse'
      operationId: postFeedback
      x-operation-id-source: derived
components:
  schemas:
    GenieFeedback:
      type: object
      required:
      - feedback_type
      - query
      - comment
      properties:
        feedback_type:
          type: string
          enum:
          - ENRICHMENT_CORRECTION
          - MISSING_ENRICHMENT
          description: "The type of feedback:\n\n - `ENRICHMENT_CORRECTION` → You would like to suggest a correction to one or more aspects of a Genie enrichment result.\n - `MISSING_ENRICHMENT` → You would like to suggest enrichment details for a query where Genie has not returned a result."
        query:
          oneOf:
          - $ref: '#/components/schemas/GenieSearchQueryItem'
          description: Details of the query that you are providing feedback on.
        match_reference:
          type: string
          description: '_Required for `ENRICHMENT_CORRECTION` feedback._


            The match reference returned by Genie for the query that you are providing feedback on.'
        _merchant:
          type: string
          description: '_Required for `ENRICHMENT_CORRECTION` feedback if Genie returned a merchant as part of the result._


            The merchant identifier returned by Genie.'
        _outlet:
          type: string
          description: '_Required for `ENRICHMENT_CORRECTION` feedback if Genie returned an outlet as part of the result._


            The outlet identifier returned by Genie.'
        _category:
          type: string
          description: '_Required for `ENRICHMENT_CORRECTION` feedback._


            The NZFCC category code returned by Genie.'
        comment:
          type: string
          maxLength: 2048
          description: Free-text field for the content of your feedback.
    GenieSearchQueryItem:
      type: object
      properties:
        id:
          type: string
          description: A unique correlation ID for the query to help you to find the corresponding result in the response data.
        description:
          type: string
          description: The transaction description. This should be the full description as provided by the bank / transaction source.
        _connection:
          type: string
          description: "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.\n\nThe following connection identifiers are available:\n  - ANZ: `conn_cjgaawozb000001nyd111xixr`\n  - ASB: `conn_cjgaaqcna000001ldwof8tvj0`\n  - BNZ: `conn_cjgaatd57000001pe1t1z0iy9`\n  - Heartland: `conn_ck5rhsdbv0000ftx1bmdu9zas`\n  - Kiwibank: `conn_cjgaac5at000001qi2yw8ftil`\n  - Rabobank: `conn_ckydkmy3r000009mde2sx2i4d`\n  - The Cooperative Bank: `conn_cjgab1c8e000001pmyxrkhova`\n  - TSB: `conn_cjgab6fis000001qsytf1semy`\n  - Westpac: `conn_cjgaaozdo000001mrnqmkl1m0`\n"
          enum:
          - conn_cjgaawozb000001nyd111xixr
          - conn_cjgaaqcna000001ldwof8tvj0
          - conn_cjgaatd57000001pe1t1z0iy9
          - conn_ck5rhsdbv0000ftx1bmdu9zas
          - conn_cjgaac5at000001qi2yw8ftil
          - conn_ckydkmy3r000009mde2sx2i4d
          - conn_cjgab1c8e000001pmyxrkhova
          - conn_cjgab6fis000001qsytf1semy
          - conn_cjgaaozdo000001mrnqmkl1m0
        amount:
          type: number
          description: Transaction amount (+ for credit, - for debit).
        direction:
          type: string
          description: Whether the transaction is a debit or credit.
          enum:
          - DEBIT
          - CREDIT
        type:
          type: string
          description: The type of transaction this query relates to.
          enum:
          - CARD
          - DIRECT DEBIT
          - PAYMENT
          - STANDING ORDER
        meta:
          type: object
          properties:
            other_account:
              type: string
              pattern: ^\d{2}-\d{4}-\d{7}-0?\d{2}$
              description: The payee bank account number.
            merchant_name:
              type: string
              description: 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:
              type: string
              description: The merchant's city.
            merchant_country:
              type: string
              description: The merchant's country.
    GenieErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
          description: A description of the error that has occurred
      required:
      - success
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token based API authentication
x-samples-languages:
- shell
- csharp
- java
- node
- python
- go
- php
- ruby
x-provenance:
  method: searched
  source: https://developers.akahu.nz/reference
  harvested: '2026-10-26'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.akahu.nz/reference/geniegetcategory.md
  - https://developers.akahu.nz/reference/geniegetmerchant.md
  - https://developers.akahu.nz/reference/geniegetoutlet.md
  - https://developers.akahu.nz/reference/geniegetpublickey.md
  - https://developers.akahu.nz/reference/geniesearch.md
  - https://developers.akahu.nz/reference/post_feedback.md
  merge:
    pages: 6
    deduped: 22
    conflicts_kept_first: 0