OneOffIdentity

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-one-off-identity-schema.json",
  "title": "OneOffIdentity",
  "description": "One of Identity [Model](/docs/the-oneoff-identity-result-model)",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-identity-api-openapi.yml#/components/schemas/OneOffIdentity",
  "type": "object",
  "properties": {
    "_id": {
      "$ref": "#/$defs/IdentityRequestId"
    },
    "status": {
      "type": "string",
      "enum": [
        "PROCESSING",
        "COMPLETE",
        "ERROR"
      ],
      "description": "- `PROCESSING` → Identity request is in progress, continue to poll for a final state of `COMPLETE` or `ERROR`.\n\n- `COMPLETE` → Final success status reached and identity data has been returned.\n\n- `ERROR` → Final error status reached due to a fatal error occurred during processing.\n\nFor more details about one of identity statuses see:\n  - [📖 Identity Status reference](/docs/the-oneoff-identity-result-model#identity-status)"
    },
    "source": {
      "description": "The source / connection that provided the identity data.",
      "$ref": "#/$defs/ConnectionInfo"
    },
    "accounts": {
      "type": "array",
      "description": "Identity information registered on linked accounts",
      "items": {
        "$ref": "#/$defs/OneOffIdentityAccount"
      }
    },
    "identities": {
      "type": "array",
      "description": "List of identity information derived from a user's connected accounts.",
      "items": {
        "$ref": "#/$defs/Identities"
      }
    },
    "addresses": {
      "type": "array",
      "description": "List of addresses derived from a user's connected accounts.",
      "items": {
        "$ref": "#/$defs/Addresses"
      }
    }
  },
  "$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."
    },
    "Addresses": {
      "type": "object",
      "description": "Address derived from a user's connected accounts.",
      "properties": {
        "type": {
          "$ref": "#/$defs/AddressType"
        },
        "value": {
          "type": "string",
          "description": "The raw address value provided by the bank."
        },
        "formatted_address": {
          "type": "string",
          "description": "Optional parsed and formatted address string."
        },
        "place_id": {
          "type": "string",
          "description": "Google Places identifier from [Google Places API](https://developers.google.com/maps/documentation/places/web-service/overview)."
        },
        "components": {
          "$ref": "#/$defs/AddressComponents",
          "description": "Breakdown of the parts that make up this address."
        }
      }
    },
    "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_`."
    },
    "ConnectionInfo": {
      "type": "object",
      "description": "Information about the financial institution where the account is held (eg. ANZ bank).",
      "properties": {
        "_id": {
          "$ref": "#/$defs/ConnectionId"
        },
        "name": {
          "type": "string",
          "description": "Display name for the connected institution."
        },
        "logo": {
          "type": "string",
          "format": "uri",
          "description": "A URL pointing to an image of the institution's logo."
        },
        "connection_type": {
          "$ref": "#/$defs/ConnectionType"
        }
      },
      "required": [
        "_id",
        "name",
        "logo",
        "connection_type"
      ]
    },
    "ConnectionType": {
      "type": "string",
      "description": "The type of integration used to connect to this institution.\n\nThis will be one of:\n- `classic` A classic Akahu connection, which uses Akahu's custom built integration to connect to the institution.\n- `official` An official open banking connection, which uses the institution's official open banking APIs.",
      "enum": [
        "classic",
        "official"
      ]
    },
    "Identities": {
      "type": "object",
      "description": "Identity information derived from a user's connected accounts.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of one of the account holders."
        },
        "formatted_account": {
          "type": "string",
          "description": "Bank account number of the account this holder was derived from."
        },
        "meta": {
          "type": "object",
          "description": "Currently reserved for future use to house additional metadata about the user."
        }
      }
    },
    "IdentityRequestId": {
      "type": "string",
      "format": "cuid",
      "pattern": "^id_[a-z0-9]{25,27}$",
      "description": "A unique Akahu identity identifier."
    },
    "OneOffIdentityAccount": {
      "type": "object",
      "description": "Identity Account",
      "properties": {
        "bank": {
          "type": "string",
          "description": "Display name of the bank"
        },
        "account_number": {
          "type": "string",
          "description": "Unique bank account identifer"
        },
        "holder": {
          "type": "string",
          "description": "Names of the owner of the account"
        },
        "has_unlisted_holders": {
          "type": "boolean",
          "description": "Indicates if the account has other holders that are not listed in the holder field. This only applies to official open banking connections where the institution indicates a joint account, but only provides the authorising party's name."
        }
      }
    }
  }
}