{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-genie-feedback-schema.json",
  "title": "GenieFeedback",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-genie-transaction-enrichment-api-openapi.yml#/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": "#/$defs/GenieSearchQueryItem"
        }
      ],
      "description": "Details of the query that you are providing feedback on."
    },
    "match_reference": {
      "type": "string",
      "description": "_Required for `ENRICHMENT_CORRECTION` feedback._\n\nThe 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._\n\nThe merchant identifier returned by Genie."
    },
    "_outlet": {
      "type": "string",
      "description": "_Required for `ENRICHMENT_CORRECTION` feedback if Genie returned an outlet as part of the result._\n\nThe outlet identifier returned by Genie."
    },
    "_category": {
      "type": "string",
      "description": "_Required for `ENRICHMENT_CORRECTION` feedback._\n\nThe NZFCC category code returned by Genie."
    },
    "comment": {
      "type": "string",
      "maxLength": 2048,
      "description": "Free-text field for the content of your feedback."
    }
  },
  "$defs": {
    "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."
            }
          }
        }
      }
    }
  }
}