AccessRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-access-request-schema.json",
  "title": "AccessRequest",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-auth-api-openapi.yml#/components/schemas/AccessRequest",
  "oneOf": [
    {
      "$ref": "#/$defs/EnduringAccessRequest"
    },
    {
      "$ref": "#/$defs/EnduringPaymentConsentRequest"
    }
  ],
  "$defs": {
    "AccountId": {
      "type": "string",
      "format": "cuid",
      "pattern": "^acc_[a-z0-9]{25,27}$",
      "description": "A unique identifier for the account in the Akahu system. It is always prefixed by `acc_` so that you can tell that it belongs to an account."
    },
    "BankAccountNumber": {
      "type": "string",
      "pattern": "^\\d{2}-\\d{4}-\\d{7}-\\d{2,3}$"
    },
    "ConnectionId": {
      "type": "string",
      "format": "cuid",
      "pattern": "^conn_[a-z0-9]{25,27}$",
      "description": "The connected financial institution's unique identifier. This will always be prefixed with `conn_`."
    },
    "ConnectionIdArray": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ConnectionId"
      }
    },
    "ConnectionStub": {
      "type": "string",
      "enum": [
        "amex",
        "amex:classic",
        "anz",
        "anz:classic",
        "anz:official",
        "asb",
        "asb:classic",
        "asb:official",
        "bnz",
        "bnz:classic",
        "bnz:official",
        "booster",
        "booster:classic",
        "coop",
        "coop:classic",
        "demo_bank",
        "demo_bank:classic",
        "demo_bank:official",
        "fisher_funds",
        "fisher_funds:classic",
        "generate",
        "generate:classic",
        "hatch",
        "hatch:classic",
        "hatch:official",
        "heartland",
        "heartland:classic",
        "ird",
        "ird:classic",
        "pie_funds",
        "pie_funds:classic",
        "kernel",
        "kernel:classic",
        "kiwibank",
        "kiwibank:classic",
        "kiwibank:official",
        "latitude",
        "latitude:classic",
        "milford",
        "milford:classic",
        "nzhl",
        "nzhl:classic",
        "nzhl:official",
        "rabobank",
        "rabobank:classic",
        "sbs",
        "sbs:classic",
        "sharesies",
        "sharesies:classic",
        "sharesight",
        "sharesight:classic",
        "simplicity",
        "simplicity:classic",
        "stake",
        "stake:classic",
        "superlife",
        "superlife:classic",
        "tsb",
        "tsb:classic",
        "westpac",
        "westpac:classic",
        "westpac:official",
        "wise",
        "wise:classic"
      ]
    },
    "ConnectionStubArray": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ConnectionStub"
      }
    },
    "ConnectionsArray": {
      "anyOf": [
        {
          "$ref": "#/$defs/ConnectionIdArray"
        },
        {
          "$ref": "#/$defs/ConnectionStubArray"
        }
      ],
      "description": "Which connections your application is requesting access to for this request.\nDefaults to connections enabled for your application."
    },
    "EnduringAccessConstraints": {
      "type": "object",
      "properties": {
        "transactions": {
          "$ref": "#/$defs/TransactionConstraints"
        },
        "payments": {
          "$ref": "#/$defs/EnduringAccessPaymentRequestApiView"
        }
      },
      "description": "Any constraints on this access request."
    },
    "EnduringAccessPaymentRequestApiView": {
      "type": "object",
      "properties": {
        "single_limit": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "The single payment limit for payments initiated under this consent."
        },
        "periodic_limit": {
          "$ref": "#/$defs/EnduringPaymentPeriodLimit"
        },
        "payees": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EnduringPayee"
          },
          "minItems": 1,
          "description": "The payees that are authorized to receive payments under this consent. At least one payee must be specified."
        }
      },
      "required": [
        "single_limit",
        "periodic_limit",
        "payees"
      ],
      "description": "The payment consent details for this request."
    },
    "EnduringAccessRequest": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "enduring_access"
          ]
        },
        "connections": {
          "$ref": "#/$defs/ConnectionsArray"
        },
        "scope": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EnduringAccessScope"
          },
          "description": "Which scopes your application is requesting access for this request.\nDefaults to all scopes enabled for your application.\nIf the user already has a previous authorisation with less or more scopes, this will not trigger a replacement."
        },
        "constraints": {
          "$ref": "#/$defs/EnduringAccessConstraints"
        }
      },
      "required": [
        "type"
      ]
    },
    "EnduringAccessScope": {
      "type": "string",
      "enum": [
        "user:basic",
        "user:email",
        "identity:name",
        "identity:dob",
        "identity:email",
        "identity:phone",
        "identity:address",
        "identity:tax_number",
        "accounts:basic",
        "accounts:balance",
        "accounts:details",
        "accounts:owner",
        "transactions:credits",
        "transactions:debits",
        "payments"
      ]
    },
    "EnduringPayee": {
      "anyOf": [
        {
          "$ref": "#/$defs/PaymentConsentStaticPayeeInput"
        },
        {
          "$ref": "#/$defs/PaymentConsentRegisteredPayeeInput"
        },
        {
          "$ref": "#/$defs/PaymentConsentInlinePayeeInput"
        }
      ]
    },
    "EnduringPaymentConsentRequest": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "enduring_payment_consent"
          ]
        },
        "_user": {
          "$ref": "#/$defs/UserId"
        },
        "_account": {
          "$ref": "#/$defs/AccountId"
        },
        "payment_consent": {
          "$ref": "#/$defs/EnduringPaymentConstraints"
        }
      },
      "required": [
        "type",
        "_user",
        "_account"
      ]
    },
    "EnduringPaymentConstraints": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "default": "Default",
          "description": "The label that groups these payment constraints.\nThis is used to help distinguish between multiple payment consents for the same account.\nWhen re-consenting, this label will ensure that the old consent with the same label is replaced by the new one."
        },
        "single_limit": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "The single payment limit for payments initiated under this consent."
        },
        "periodic_limit": {
          "$ref": "#/$defs/EnduringPaymentPeriodLimit"
        },
        "payees": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EnduringPayee"
          },
          "minItems": 1,
          "description": "The payees that are authorized to receive payments under this consent, at least one payee must be specified."
        }
      },
      "required": [
        "single_limit",
        "periodic_limit",
        "payees"
      ],
      "description": "The payment consent details for this request."
    },
    "EnduringPaymentFrequency": {
      "type": "string",
      "enum": [
        "DAILY",
        "WEEKLY",
        "FORTNIGHTLY",
        "MONTHLY",
        "ANNUALLY"
      ],
      "description": "The frequency at which the periodic limit applies, this is used in combination with the amount to determine the periodic limit. (E.g. $1 daily)"
    },
    "EnduringPaymentPeriodLimit": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "The amount that can be paid in the specified frequency period."
        },
        "frequency": {
          "$ref": "#/$defs/EnduringPaymentFrequency"
        }
      },
      "required": [
        "amount",
        "frequency"
      ],
      "description": "The periodic payment limit for payments initiated under this consent."
    },
    "PayeeId": {
      "type": "string",
      "pattern": "^payee_[a-z0-9]{25,27}$"
    },
    "PaymentConsentInlinePayeeInput": {
      "oneOf": [
        {
          "$ref": "#/$defs/PaymentConsentInlinePayeeInputNoneVerified"
        },
        {
          "$ref": "#/$defs/PaymentConsentInlinePayeeInputClientVerified"
        },
        {
          "$ref": "#/$defs/PaymentConsentInlinePayeeInputVerifiedVerified"
        }
      ]
    },
    "PaymentConsentInlinePayeeInputClientVerified": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "INLINE"
          ]
        },
        "account_number": {
          "$ref": "#/$defs/BankAccountNumber"
        },
        "name": {
          "type": "string",
          "minLength": 3,
          "maxLength": 200
        },
        "verification_method": {
          "type": "string",
          "enum": [
            "CLIENT_VERIFIED"
          ],
          "description": " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
        }
      },
      "required": [
        "source",
        "account_number",
        "name",
        "verification_method"
      ]
    },
    "PaymentConsentInlinePayeeInputNoneVerified": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "INLINE"
          ]
        },
        "account_number": {
          "$ref": "#/$defs/BankAccountNumber"
        },
        "name": {
          "type": "string",
          "minLength": 3,
          "maxLength": 200
        },
        "verification_method": {
          "type": "string",
          "enum": [
            "NONE"
          ],
          "description": " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
        }
      },
      "required": [
        "source",
        "account_number",
        "name",
        "verification_method"
      ]
    },
    "PaymentConsentInlinePayeeInputVerifiedVerified": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "INLINE"
          ]
        },
        "verification_method": {
          "type": "string",
          "enum": [
            "VERIFICATION_TOKEN"
          ],
          "description": " - `VERIFICATION_TOKEN` → The payee name and account number are\nverified using an Akahu account verification token. The details of payees verified in this way are sourced from the account verification token and cannot be modified by the client.\n - `NONE` → This verification method is restricted for use by specific clients.\n - `CLIENT_VERIFIED` → This verification method is restricted for use by specific clients."
        },
        "verification_token": {
          "type": "string"
        }
      },
      "required": [
        "source",
        "verification_method",
        "verification_token"
      ]
    },
    "PaymentConsentRegisteredPayeeInput": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "REGISTERED"
          ]
        },
        "_payee": {
          "$ref": "#/$defs/PayeeId"
        }
      },
      "required": [
        "source",
        "_payee"
      ]
    },
    "PaymentConsentStaticPayeeInput": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "STATIC"
          ]
        },
        "account_number": {
          "$ref": "#/$defs/BankAccountNumber"
        }
      },
      "required": [
        "source",
        "account_number"
      ]
    },
    "TransactionConstraints": {
      "type": "object",
      "properties": {
        "start_date": {
          "type": "string",
          "format": "date",
          "description": "The start date for transactions to be requested from for new consents, this is in the Pacific/Auckland timezone."
        }
      },
      "required": [
        "start_date"
      ],
      "description": "Any constraints on transaction data that should be included in this access request, uses app defaults if not specified."
    },
    "UserId": {
      "type": "string",
      "pattern": "^user_[a-z0-9]{25,27}$"
    }
  }
}