Akahu Parties API

openapi: 3.2.0
info:
  title: Akahu One-Off REST Parties API
  description: Retrieve a one-off snapshot of a user's account data
  version: 1.0.0
servers:
- url: https://api.oneoff.akahu.io/v1
tags:
- name: Parties
paths:
  /parties/{code}:
    get:
      tags:
      - Parties
      summary: Get Parties
      security:
      - app_auth: []
      parameters:
      - $ref: '#/components/parameters/Code'
      - $ref: '#/components/parameters/ContentType'
      description: 'Get identity data related to the registered party at the institution that the user has shared data from. This data is sourced from the profile information at the connected institution rather than any specific account held within.


        In general this identity data will relate to the person who has connected the account, however if the user connects an account that is registered under another party (e.g. another person, an LLC, a trust), the result may also contain data pertaining to these other parties. That is to say, Akahu is simply passing this information on from the institution.


        > ℹ️

        >

        > This endpoint returns an array of items for consistency with the parties response from our enduring account connectivity API. However, because each one-off account connection flow relates to only a single session at a single institution, this endpoint will only ever return at-most one party item.'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Party'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: getPartiesByCode
      x-operation-id-source: derived
components:
  schemas:
    Party:
      type: object
      description: Identity data related to the registered party at the financial institution that the user has shared their data from. This data is sourced from the profile information at the connected institution rather than any specific account held within.
      properties:
        name:
          $ref: '#/components/schemas/PartyName'
        dob:
          type: string
          description: The party's date of birth (yyyy-mm-dd) if available. Your app must have the `IDENTITY_DOBS` scope, otherwise this field will be undefined.
        tax_number:
          type: string
          description: The party's tax number if available. Your app must have the `IDENTITY_TAX_NUMBERS` scope, otherwise this field will be undefined.
        pir:
          type: number
          description: The party's Prescribed Investor Rate (PIR) if available. Your app must have the `IDENTITY_TAX_NUMBERS` scope, otherwise this field will be undefined.
        email_addresses:
          type: array
          description: The party's email addresses. Your app must have the `IDENTITY_EMAILS` scope, otherwise an empty array will be returned.
          items:
            $ref: '#/components/schemas/PartyEmailAddress'
        phone_numbers:
          type: array
          description: The party's phone numbers. Your app must have the `IDENTITY_PHONES` scope, otherwise an empty array will be returned.
          items:
            $ref: '#/components/schemas/PartyPhoneNumber'
        addresses:
          type: array
          description: The party's addresses. Your app must have the `IDENTITY_ADDRESSES` scope, otherwise an empty array will be returned.
          items:
            $ref: '#/components/schemas/PartyAddress'
      required:
      - email_addresses
      - phone_numbers
      - addresses
    PartyPhoneNumber:
      type: object
      description: A party's phone number
      properties:
        subtype:
          type: string
          description: 'The phone number type.


            - `MOBILE` → The party''s mobile phone number.

            - `HOME` → The party''s home phone number.

            - `WORK` → The party''s work phone number.'
          enum:
          - MOBILE
          - HOME
          - WORK
        value:
          type: string
          description: The phone number string as provided by the financial institution.
          example: '+64271234567'
        verified:
          type: boolean
          description: Whether the phone number has been verified by the financial institution.
          example: true
      required:
      - subtype
      - value
      - verified
    PartyNameComponents:
      type: object
      description: A party's name components. All components are optional as format depends on how the data is provided by the bank.
      properties:
        prefix:
          type: string
          description: The party's prefix, e.g. Mr
          example: Mr
        initials:
          type: string
          description: The party's initials (Excluding surname), e.g. RJJ for 'Robert John Joseph Smith'
          example: RJJ
        preferred_name:
          type: string
          description: The party's preferred name, if they have specified this at their bank e.g. Bob instead of Robert
          example: Bob
        given_name:
          type: string
          description: The party's given name, e.g. Robert
          example: Robert
        middle_name:
          type: string
          description: The party's middle name(s), if any, e.g. John Joseph
          example: John Joseph
        surname:
          type: string
          description: The party's surname
          example: Smith
    PartyEmailAddress:
      type: object
      description: A party's email address
      properties:
        subtype:
          type: string
          description: 'The email address type.


            - `PRIMARY` → The party''s primary email address.

            - `SECONDARY` → The party''s secondary email address.'
          enum:
          - PRIMARY
          - SECONDARY
        value:
          type: string
          description: The email address string as provided by the financial institution.
          example: hello@akahu.nz
        verified:
          type: boolean
          description: Whether the email address has been verified by the financial institution.
          example: true
      required:
      - subtype
      - value
      - verified
    PartyName:
      type: object
      description: A party's name if available. Your app must have the `IDENTITY_NAMES` scope, otherwise this field will be undefined.
      properties:
        value:
          type: string
          description: The full name string as provided by the financial institution.
          example: MR ROBERT JOHN JOSEPH SMITH
        components:
          $ref: '#/components/schemas/PartyNameComponents'
      required:
      - value
    PartyAddress:
      type: object
      description: A party's address
      properties:
        subtype:
          type: string
          description: 'The address type.


            - `RESIDENTIAL` → Where the party lives.

            - `POSTAL` → Where the party receives their postage. (May be the same as the residential address)'
          enum:
          - RESIDENTIAL
          - POSTAL
        value:
          type: string
          description: The raw address string as provided by the financial institution.
          example: 999 QUEEN STREET, AUCKLAND CBD, AUCKLAND, 1010, NEW ZEALAND
        formatted:
          type: string
          description: The address having been parsed and formatted uniformly by Akahu
          example: 999 Queen Street, Auckland CBD, Auckland 1010, New Zealand
        components:
          type: object
          description: The parsed address components
          properties:
            street:
              type: string
              description: The address's street number and name
            suburb:
              type: string
              description: The address's suburb
            city:
              type: string
              description: The address's city
            region:
              type: string
              description: The address's region
            postal_code:
              type: string
              description: The address's postal code
            country:
              type: string
              description: The address's country
        google_maps_place_id:
          type: string
          description: The Place ID for the address if using the Google Maps APIs
      required:
      - subtype
      - value
  parameters:
    Code:
      name: code
      in: path
      required: true
      description: The one-off authorization code, provided to your application by redirection to your `redirect_uri` upon the user's successful completion of the authorization flow.
      example: id_1111111111111111111111111
      schema:
        type: string
    ContentType:
      name: Content-Type
      in: header
      schema:
        type: string
      example: application/json
  responses:
    '400':
      description: Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Invalid Content-Type
    '500':
      description: An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Something went wrong
    '403':
      description: You are not allowed to access this content.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Forbidden
    '401':
      description: You are not authorised to access this content.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Permission Denied
  securitySchemes:
    app_auth:
      type: http
      scheme: basic
      description: 'HTTP Basic Auth with the username being your **App ID Token** and the password being your **App Secret**.

        > `Basic {app_token}:{app_secret}`


        This must be included in all requests to the one-off API.'
x-provenance:
  method: searched
  source: https://developers.akahu.nz/reference
  harvested: '2026-10-26'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.akahu.nz/reference/get_accounts-code.md
  - https://developers.akahu.nz/reference/get_parties-code.md
  - https://developers.akahu.nz/reference/get_pdfs-exports-code.md
  - https://developers.akahu.nz/reference/get_pdfs-statements-code.md
  - https://developers.akahu.nz/reference/get_status-code.md
  - https://developers.akahu.nz/reference/get_transactions-code.md
  - https://developers.akahu.nz/reference/post_identity-code-verify-name.md
  merge:
    pages: 7
    deduped: 42
    conflicts_kept_first: 0