ReportAccount

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-report-account-schema.json",
  "title": "ReportAccount",
  "description": "Each financial account included in the Report dataset is represented by an Account record. If data relating to the same financial account is included in multiple Resources, the data will be combined (deduplicated) into a single Account record.",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-apply-api-openapi.yml#/components/schemas/ReportAccount",
  "type": "object",
  "properties": {
    "_id": {
      "allOf": [
        {
          "$ref": "#/$defs/ReportAccountId"
        },
        {
          "type": "string"
        }
      ]
    },
    "type": {
      "type": "string",
      "enum": [
        "DEPOSITORY",
        "CREDIT CARD",
        "LOAN",
        "TERM DEPOSIT",
        "KIWISAVER",
        "INVESTMENT",
        "UNKNOWN"
      ],
      "description": "Types of account:\n - `DEPOSITORY` A regular transactional or savings bank account.\n - `CREDIT CARD` A credit card or charge card.\n - `LOAN` A loan account, including line-of-credit accounts such as revolving home loans.\n - `TERM DEPOSIT` A term deposit.\n - `KIWISAVER` A KiwiSaver account.\n - `INVESTMENT` A generic investment account, e.g. A shares portfolio.\n - `UNKNOWN` An unsupported account type."
    },
    "identifier": {
      "type": [
        "string",
        "null"
      ],
      "description": "If available, an official identifier such as an NZ bank account number or credit card number."
    },
    "name": {
      "type": "string"
    },
    "holder": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name of the account holder."
    },
    "ownership_type": {
      "$ref": "#/$defs/AccountOwnershipType"
    },
    "provider": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "logo": {
          "type": "string",
          "description": "A URL pointing to a logo for this provider."
        }
      },
      "required": [
        "_id",
        "name",
        "logo"
      ],
      "description": "The institution that provides data (eg. a bank, a card issuer)."
    },
    "periods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "_source": {
            "type": "string",
            "pattern": "^src_[a-z0-9]{24,27}$",
            "description": "The data source that supplied information in this period"
          },
          "opening_balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "The opening balance for the account in this period, if available."
          },
          "closing_balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "The closing balance for the account in this period, if available."
          },
          "limit": {
            "type": [
              "number",
              "null"
            ],
            "description": "The credit limit for the account in this period, if available."
          },
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "The start date of the period."
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "description": "The end date of the period."
          }
        },
        "required": [
          "_source",
          "opening_balance",
          "closing_balance",
          "limit",
          "start",
          "end"
        ],
        "description": "A period of data pertaining to this account."
      },
      "description": "Periods of data that have been extracted pertaining to this account."
    },
    "loan": {
      "type": "object",
      "properties": {
        "purpose": {
          "$ref": "#/$defs/AccountLoanPurpose"
        },
        "interest": {
          "type": "object",
          "properties": {
            "type": {
              "$ref": "#/$defs/AccountLoanInterestType"
            },
            "rate": {
              "type": "number",
              "description": "The interest rate percentage for this account, e.g. 6.49 for 6.49%."
            },
            "expires_at": {
              "type": "string",
              "format": "date-time",
              "description": "When the interest rate expires, if available. This is the date after which the interest rate may change."
            }
          },
          "required": [
            "type"
          ]
        },
        "interest_only_expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the interest only period expires, if available. This is the date after which the borrower will need to start repaying the principal in addition to the interest."
        },
        "term": {
          "$ref": "#/$defs/AccountLoanTerm"
        },
        "matures_at": {
          "type": "string",
          "format": "date-time",
          "description": "Loan maturity date refers to the date on which a borrower's final loan payment is due."
        },
        "initial_principal": {
          "type": "number",
          "description": "The loan initial principal amount, this was the original amount borrowed."
        },
        "repayment": {
          "$ref": "#/$defs/AccountLoanRepayment"
        }
      },
      "required": [
        "purpose",
        "interest",
        "repayment"
      ],
      "description": "Any loan information associated with the account."
    }
  },
  "required": [
    "_id",
    "type",
    "identifier",
    "name",
    "holder",
    "provider",
    "periods"
  ],
  "$defs": {
    "AccountLoanInterestType": {
      "type": "string",
      "enum": [
        "FLOATING",
        "FIXED",
        "UNKNOWN"
      ],
      "description": "The type of interest rate:\n\n- `FLOATING`: This account has a variable interest rate.\n\n- `FIXED`: This account has a fixed interest rate.\n\n- `UNKNOWN`: We could not determine the interest type for this account."
    },
    "AccountLoanPurpose": {
      "type": "string",
      "enum": [
        "HOME",
        "PERSONAL",
        "VEHICLE",
        "BUSINESS",
        "UNKNOWN"
      ],
      "description": "The purpose of the loan:\n\n - `HOME`: This is a home loan facility.\n\n - `PERSONAL`: This is a personal loan facility.\n\n - `VEHICLE`: This is a vehicle loan facility, if it can be distinguished from a personal loan.\n\n - `BUSINESS`: This is a business loan facility.\n\n - `UNKNOWN`: We could not determine what this loan is for."
    },
    "AccountLoanRepayment": {
      "type": "object",
      "properties": {
        "structure": {
          "$ref": "#/$defs/AccountLoanRepaymentStructure"
        },
        "frequency": {
          "$ref": "#/$defs/AccountLoanRepaymentFrequency"
        },
        "next_date": {
          "type": "string",
          "format": "date-time",
          "description": "The date of the next repayment instalment, if available."
        },
        "next_amount": {
          "type": "number",
          "description": "The amount of the next repayment instalment, if available."
        }
      },
      "required": [
        "structure"
      ],
      "description": "Loan repayment information for an account."
    },
    "AccountLoanRepaymentFrequency": {
      "type": "string",
      "enum": [
        "WEEKLY",
        "FORTNIGHTLY",
        "MONTHLY",
        "QUARTERLY",
        "BIANNUALLY",
        "ANNUALLY"
      ],
      "description": "The frequency of repayments for a loan:\n\n- `WEEKLY`: Repayments are made every week.\n\n- `FORTNIGHTLY`: Repayments are made every two weeks.\n\n- `MONTHLY`: Repayments are made every month.\n\n- `QUARTERLY`: Repayments are made every three months.\n\n- `BIANNUALLY`: Repayments are made every six months.\n\n- `ANNUALLY`: Repayments are made every year."
    },
    "AccountLoanRepaymentStructure": {
      "type": "string",
      "enum": [
        "PRINCIPAL_AND_INTEREST",
        "REVOLVING",
        "INTEREST_ONLY",
        "UNKNOWN"
      ],
      "description": "The high-level repayment structure of a loan:\n\n - `PRINCIPAL_AND_INTEREST`: Regular repayments include both interest and principal.\n\n - `REVOLVING`: Sometimes called a “line of credit” or “revolving credit mortgage”. The idea is to help save on interest by reducing your daily loan balance as much as possible. You can do this by direct crediting all your income into the account and then paying your bills and everyday expenses from the account as you need to. Revolving loans have a floating (or variable) interest rate. The interest is calculated on the daily balance of your account, so by keeping the loan as low as you can, for as long as you can, you should pay less interest.\n\n - `INTEREST_ONLY`: You don’t repay any of the money you’ve borrowed (principal) until an agreed time. In the meantime you make regular interest payments.\n\n - `UNKNOWN`: We could not determine the repayment structure for this account."
    },
    "AccountLoanTerm": {
      "type": "object",
      "properties": {
        "years": {
          "type": "number"
        },
        "months": {
          "type": "number"
        }
      },
      "description": "The duration/term of the loan for it to be paid to completion from the start date of the loan."
    },
    "AccountOwnershipType": {
      "type": "string",
      "enum": [
        "SOLE",
        "JOINT",
        "UNKNOWN"
      ]
    },
    "ReportAccountId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^report_acc_[a-z0-9]{24,27}$"
    }
  }
}