Party

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-party-schema.json",
  "title": "Party",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-identity-api-openapi.yml#/components/schemas/Party",
  "type": "object",
  "required": [
    "_id",
    "_connection",
    "_user",
    "_authorisation",
    "type"
  ],
  "properties": {
    "_id": {
      "type": "string",
      "description": "The unique identifier for this party"
    },
    "_connection": {
      "type": "string",
      "description": "The connection ID. This identifies which financial institution this data was sourced from."
    },
    "_user": {
      "type": "string",
      "description": "The Akahu user ID that identifies the user that this party is associated with."
    },
    "_authorisation": {
      "type": "string",
      "description": "The authorisation identifier. Financial accounts are connected to Akahu via an authorisation with the user's financial institution. This identifier can be used to link specific financial accounts to the party who completed the authorisation by matching records with the same `_authorisation` value."
    },
    "type": {
      "type": "string",
      "deprecated": true,
      "description": "This field is included for legacy compatibility. It will always contain a fixed value of \"INDIVIDUAL\". Due to some quirks with the data held in bank systems, it is possible in rare cases that a company name is returned instead of an individual name. This can happen for small business accounts where bank staff have set up a user profile for a company instead of a person.",
      "enum": [
        "INDIVIDUAL"
      ]
    },
    "name": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "The party's name as provided by their connected institution."
        }
      }
    },
    "dob": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "format": "date",
          "description": "The party's date-of-birth in the format YYYY-MM-DD."
        }
      }
    },
    "tax_number": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "pattern": "^[01]\\d{3}\\.\\d{3}\\.\\d{3}$",
          "description": "The party's IRD number in the format XXX-XXX-XXX."
        }
      }
    },
    "phone_numbers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A phone number that the party has registered with their connected institution.",
        "properties": {
          "value": {
            "type": "string",
            "description": "The phone number"
          },
          "subtype": {
            "type": "string",
            "enum": [
              "MOBILE",
              "HOME",
              "WORK"
            ]
          },
          "verified": {
            "type": "boolean"
          }
        }
      }
    },
    "email_addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An email address that the party has registered with their connected institution.",
        "properties": {
          "value": {
            "type": "string",
            "description": "The email address"
          },
          "subtype": {
            "type": "string",
            "enum": [
              "PRIMARY"
            ]
          },
          "verified": {
            "type": "boolean"
          }
        }
      }
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An address that the party has registered with their connected institution.",
        "properties": {
          "value": {
            "type": "string",
            "description": "The raw address value from the connected institution."
          },
          "subtype": {
            "$ref": "#/$defs/AddressType"
          },
          "formatted": {
            "type": "string",
            "description": "A consistently formatted/normalised version of the address."
          },
          "components": {
            "$ref": "#/$defs/AddressComponents"
          },
          "google_maps_place_id": {
            "type": "string",
            "description": "Google Maps API Place ID for this address."
          }
        }
      }
    }
  },
  "$defs": {
    "AddressComponents": {
      "type": "object",
      "description": "Breakdown of the parts that make up this address.",
      "properties": {
        "street": {
          "type": "string",
          "description": "Street name from the address"
        },
        "suburb": {
          "type": "string",
          "description": "Suburb name from the address"
        },
        "city": {
          "type": "string",
          "description": "City name from the address"
        },
        "region": {
          "type": "string",
          "description": "Region name from the address"
        },
        "postal_code": {
          "type": "string",
          "description": "Postal code from the address"
        },
        "country": {
          "type": "string",
          "description": "Country from the address"
        }
      }
    },
    "AddressType": {
      "type": "string",
      "enum": [
        "RESIDENTIAL",
        "POSTAL",
        "UNKNOWN"
      ],
      "description": "Type of address:\n\n- `RESIDENTIAL` → Where the user lives.\n\n- `POSTAL` → Where the user can be reached by mail such as a PO-BOX.\n\n- `UNKNOWN` → Akahu was unable to determine which of the two types of address this is."
    }
  }
}