Akahu Resources API

openapi: 3.2.0
info:
  title: Akahu Apply Resources API
  version: 1.0.0
servers:
- url: https://api.apply.akahu.nz
  description: Akahu Apply API
tags:
- name: Resources
paths:
  /v1/applications/{applicationId}/resources:
    get:
      operationId: ListResources
      tags:
      - Resources
      summary: List resources for application
      description: Financial data is added to an Application via one or more Resources. The data from multiple resources is compiled into a single aggregate dataset by generating a Report.
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Resource'
                required:
                - items
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic400ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic401ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic403ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic404ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic429ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generic500ErrorResponse'
components:
  schemas:
    DocumentContentRange:
      type: object
      properties:
        start:
          type: number
        end:
          type: number
        outcome:
          $ref: '#/components/schemas/DocumentRangeOutcome'
        inferred_content:
          $ref: '#/components/schemas/DocumentContentType'
      required:
      - start
      - end
      - outcome
      - inferred_content
      description: Describes the processing outcome of a range of pages in a document.
    DocumentChannelSharingRequest:
      type: object
      properties:
        type:
          type: string
          enum:
          - sharing_request
        _id:
          type: string
          pattern: ^sharing_request_[a-z0-9]{24,27}$
          example: sharing_request_tz4a98xxat96iws9zmbrgj3a
          description: The ID of the sharing request that this document was used to add this document.
      required:
      - type
      - _id
      description: The document was uploaded via sharing request.
    DocumentChannelPortal:
      type: object
      properties:
        type:
          type: string
          enum:
          - portal
      required:
      - type
      description: The document was uploaded via the Akahu Apply portal.
    DocumentId:
      type: string
      pattern: ^doc_[a-z0-9]{24,27}$
      example: doc_tz4a98xxat96iws9zmbrgj3a
    DocumentSourceOneoffObConnection:
      type: object
      properties:
        type:
          type: string
          enum:
          - oneoff_ob_connection
        _id:
          type: string
          pattern: ^oneoff_ob_connection_[a-z0-9]{24,27}$
          example: oneoff_ob_connection_tz4a98xxat96iws9zmbrgj3a
          description: The ID of the one-off open banking connection that this document was sourced from.
      required:
      - type
      - _id
      description: The document was sourced directly from an open banking connection.
    Resource:
      oneOf:
      - type: object
        properties:
          _id:
            $ref: '#/components/schemas/DocumentId'
          _application:
            type: string
            pattern: ^application_[a-z0-9]{24,27}$
            example: application_tz4a98xxat96iws9zmbrgj3a
            description: The application that this document belongs to.
          type:
            type: string
            enum:
            - document
          status:
            $ref: '#/components/schemas/ResourceStatus'
          name:
            type: string
            maxLength: 255
            description: The filename of this document.
          failure_reason:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/DocumentFailureReasonCode'
              message:
                type: string
                default: Sorry, something went wrong while processing this document. Please try again later.
            required:
            - code
            description: If this document has failed to be processed, this field provides additional detail about what went wrong.
          channel:
            oneOf:
            - $ref: '#/components/schemas/DocumentChannelSharingRequest'
            - $ref: '#/components/schemas/DocumentChannelApi'
            - $ref: '#/components/schemas/DocumentChannelPortal'
            - $ref: '#/components/schemas/DocumentChannelReferral'
            discriminator:
              propertyName: type
              mapping:
                sharing_request: '#/components/schemas/DocumentChannelSharingRequest'
                api: '#/components/schemas/DocumentChannelApi'
                portal: '#/components/schemas/DocumentChannelPortal'
                referral: '#/components/schemas/DocumentChannelReferral'
            description: 'The channel that was used to create the document along with any relevant metadata for that channel.


              This field can be used to determine whether the document was created via a Sharing Request, API, or the Akahu Apply portal.'
          source:
            oneOf:
            - $ref: '#/components/schemas/DocumentSourceDirectUpload'
            - $ref: '#/components/schemas/DocumentSourceOneoffObConnection'
            discriminator:
              propertyName: type
              mapping:
                direct_upload: '#/components/schemas/DocumentSourceDirectUpload'
                oneoff_ob_connection: '#/components/schemas/DocumentSourceOneoffObConnection'
            description: 'How the document file was ingested by Akahu Apply.


              This field can be used to determine whether the document was uploaded directly from an external source, or sourced from an open banking connection.'
          content_details:
            $ref: '#/components/schemas/DocumentContentDetails'
          created_at:
            type: string
            format: date-time
            description: The date that this document was created.
          updated_at:
            type: string
            format: date-time
            description: The date that this document was last updated at.
          expires_at:
            type: string
            format: date-time
            description: "Expiry for the document, after which the record will be deleted. Expiry varies as the document progresses through its lifecycle:\n\n - While the document has a status of `pending`, expiry is short lived, ensuring that the record is cleaned up quickly if a file is never uploaded.\n\n - After the document upload has been received, a 1 year expiry is set, after which the document and all associated data will be permanently deleted."
        required:
        - _id
        - _application
        - type
        - status
        - name
        - channel
        - source
        - created_at
        - updated_at
      - type: object
        properties:
          _id:
            $ref: '#/components/schemas/DatafileId'
          _application:
            type: string
            pattern: ^application_[a-z0-9]{24,27}$
            example: application_tz4a98xxat96iws9zmbrgj3a
            description: The application that this datafile belongs to.
          type:
            type: string
            enum:
            - datafile
          status:
            $ref: '#/components/schemas/ResourceStatus'
          name:
            type: string
            maxLength: 255
            description: The filename of this datafile.
          content_type:
            type: string
            enum:
            - application/json
            description: The content type of the datafile.
          schema:
            type: string
            description: The name of the schema for this datafile.
          failure_reason:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/DatafileFailureReasonCode'
              message:
                type: string
                default: Sorry, something went wrong while processing this datafile. Please try again later.
            required:
            - code
            description: If this datafile has failed to be processed, this field provides additional detail about what went wrong.
          created_at:
            type: string
            format: date-time
            description: The date that this datafile was created.
          updated_at:
            type: string
            format: date-time
            description: The date that this datafile was last updated at.
          expires_at:
            type: string
            format: date-time
            description: "Expiry for the datafile, after which the record will be deleted. Expiry varies as the datafile progresses through its lifecycle:\n\n - While the datafile has a status of `pending`, expiry is short lived, ensuring that the record is cleaned up quickly if a file is never uploaded.\n\n - After the datafile upload has been received, a 1 year expiry is set, after which the datafile and all associated data will be permanently deleted."
        required:
        - _id
        - _application
        - type
        - status
        - name
        - content_type
        - schema
        - created_at
        - updated_at
      - type: object
        properties:
          _id:
            $ref: '#/components/schemas/OneoffOpenBankingConnectionId'
          _application:
            type: string
            pattern: ^application_[a-z0-9]{24,27}$
            example: application_tz4a98xxat96iws9zmbrgj3a
            description: The application that this open banking connection belongs to.
          type:
            type: string
            enum:
            - oneoff_ob_connection
          status:
            $ref: '#/components/schemas/ResourceStatus'
          failure_reason:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/OneoffOpenBankingConnectionFailureReasonCode'
              message:
                type: string
                default: Something went wrong while processing this connection.
            required:
            - code
            description: If this open banking connection has failed to complete, this field provides additional detail about what went wrong.
          created_at:
            type: string
            format: date-time
            description: The date that this open banking connection was created.
          updated_at:
            type: string
            format: date-time
            description: The date that this open banking connection was last updated at.
        required:
        - _id
        - _application
        - type
        - status
        - created_at
        - updated_at
      description: 'Financial data is added to an Application via one or more Resources.


        The data from multiple resources is compiled into a single aggregate dataset by generating a Report.'
    DocumentContentDetails:
      type: object
      properties:
        page_count:
          type: number
        processed_count:
          type: number
        skipped_count:
          type: number
        unprocessed_count:
          type: number
        ranges:
          type: array
          items:
            $ref: '#/components/schemas/DocumentContentRange'
      required:
      - page_count
      - processed_count
      - skipped_count
      - unprocessed_count
      - ranges
    OrgId:
      type: string
      pattern: ^org_[a-z0-9]{24,27}$
      example: org_tz4a98xxat96iws9zmbrgj3a
    DocumentRangeOutcome:
      type: string
      enum:
      - processed
      - unprocessed
      - skipped
      description: "The outcome from processing a range of pages:\n\n - `processed`: The pages were processed and data has been successfully extracted.\n\n - `skipped`: The pages skipped processing. This usually occurs because any data in the document was not required in the generation of the report (eg. a blank page).\n\n - `unprocessed`: The pages were unable to be processed. This occurs if the content is not supported by Akahu Apply, or if an error occurred during processing."
    DocumentChannelApi:
      type: object
      properties:
        type:
          type: string
          enum:
          - api
      required:
      - type
      description: The document was uploaded via API.
    DocumentSourceDirectUpload:
      type: object
      properties:
        type:
          type: string
          enum:
          - direct_upload
      required:
      - type
      description: The documented was uploaded to Akahu Apply from an external source.
    DocumentContentType:
      type: string
      enum:
      - blank
      - passport
      - drivers_license
      - financial_statement
      - income_statement
      - unknown
      description: "The inferred type of content on a given document page:\n\n - `blank`: A blank page\n\n - `financial_statement`: A financial statement\n\n - `passport`: A passport\n\n - `drivers_license`: A drivers license\n\n - `income_statement`: An income summary or statement\n\n - `unknown`: Unknown"
    Generic429ErrorResponseCode:
      type: string
      enum:
      - too_many_requests
    OneoffOpenBankingConnectionFailureReasonCode:
      type: string
      enum:
      - internal_error
      - timeout
    Generic403ErrorResponseCode:
      type: string
      enum:
      - forbidden
    Generic400ErrorResponseCode:
      type: string
      enum:
      - invalid_type
      - too_big
      - too_small
      - invalid_format
      - not_multiple_of
      - unrecognized_keys
      - invalid_union
      - invalid_key
      - invalid_element
      - invalid_value
      - invalid
      - invalid_id
    DocumentChannelReferral:
      type: object
      properties:
        type:
          type: string
          enum:
          - referral
        _id:
          type: string
          pattern: ^referral_[a-z0-9]{24,27}$
          example: referral_tz4a98xxat96iws9zmbrgj3a
          description: The ID of the referral that was used to add this document.
        original_channel_type:
          type: string
          enum:
          - sharing_request
          - api
          - portal
          description: The channel that the original document was created through.
        referrer:
          type: object
          properties:
            _id:
              $ref: '#/components/schemas/OrgId'
            name:
              type: string
            logo:
              type: string
              description: A URL referencing the org's logo in PNG format.
          required:
          - _id
          - name
          description: The organisation that referred the document.
      required:
      - type
      - _id
      description: The document was copied from a referral.
    Generic429ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic429ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    ApplicationId:
      type: string
      pattern: ^application_[a-z0-9]{24,27}$
      example: application_tz4a98xxat96iws9zmbrgj3a
    Generic401ErrorResponseCode:
      type: string
      enum:
      - unauthorized
    Generic500ErrorResponseCode:
      type: string
      enum:
      - internal_error
    OneoffOpenBankingConnectionId:
      type: string
      pattern: ^oneoff_ob_connection_[a-z0-9]{24,27}$
      example: oneoff_ob_connection_tz4a98xxat96iws9zmbrgj3a
    Generic404ErrorResponseCode:
      type: string
      enum:
      - not_found
    DatafileFailureReasonCode:
      type: string
      enum:
      - internal_error
      - invalid_input
      - timeout
      - malware_scan_failed
      - malware_detected
    DatafileId:
      type: string
      pattern: ^dat_[a-z0-9]{24,27}$
      example: dat_tz4a98xxat96iws9zmbrgj3a
    Generic500ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic500ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    Generic404ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic404ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    Generic403ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic403ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    Generic400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    DocumentFailureReasonCode:
      type: string
      enum:
      - internal_error
      - invalid_input
      - password_protected
      - timeout
      - malware_scan_failed
      - malware_detected
    Generic401ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                $ref: '#/components/schemas/Generic401ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    IssuePath:
      type: array
      items:
        title: IssuePathSegment
        oneOf:
        - type: string
        - type: integer
    ResourceStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - failed
      description: "The status of a resource:\n\n - `pending` The resource record exists, but has not yet been fully loaded.\n\n - `processing` The data from this record is being extracted and processed.\n\n - `completed` This resource has been successfully processed.\n\n - `failed` This resource has not been successfully processed. See the `failure_reason` for more detail."
  securitySchemes:
    APIKey:
      type: http
      scheme: bearer
      description: Bearer auth using an Akahu Apply API Key. These can be generated by an Akahu Apply administrator in the web portal.
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/archiveapplication.md
  - https://developers.akahu.nz/reference/createapplication.md
  - https://developers.akahu.nz/reference/createdatafile.md
  - https://developers.akahu.nz/reference/createdocument.md
  - https://developers.akahu.nz/reference/createreferral.md
  - https://developers.akahu.nz/reference/createreferralredemption.md
  - https://developers.akahu.nz/reference/createreport.md
  - https://developers.akahu.nz/reference/createsharingrequest.md
  - https://developers.akahu.nz/reference/deletedatafile.md
  - https://developers.akahu.nz/reference/deletedocument.md
  - https://developers.akahu.nz/reference/downloaddatafile.md
  - https://developers.akahu.nz/reference/downloaddocument.md
  - https://developers.akahu.nz/reference/getapplication.md
  - https://developers.akahu.nz/reference/getcurrentorg.md
  - https://developers.akahu.nz/reference/getdatafile.md
  - https://developers.akahu.nz/reference/getdocument.md
  - https://developers.akahu.nz/reference/getreferral.md
  - https://developers.akahu.nz/reference/getreferralredemption.md
  - https://developers.akahu.nz/reference/getreport.md
  - https://developers.akahu.nz/reference/getreportaccounts.md
  - https://developers.akahu.nz/reference/getreportdatasources.md
  - https://developers.akahu.nz/reference/getreporthtmldownload.md
  - https://developers.akahu.nz/reference/getreportinsights.md
  - https://developers.akahu.nz/reference/getreportjsondownload.md
  - https://developers.akahu.nz/reference/getreporttransactions.md
  - https://developers.akahu.nz/reference/getsharingrequest.md
  - https://developers.akahu.nz/reference/listdatafiles.md
  - https://developers.akahu.nz/reference/listdocuments.md
  - https://developers.akahu.nz/reference/listreferrals.md
  - https://developers.akahu.nz/reference/listresources.md
  - https://developers.akahu.nz/reference/revokereferral.md
  - https://developers.akahu.nz/reference/unarchiveapplication.md
  - https://developers.akahu.nz/reference/updateapplication.md
  merge:
    pages: 33
    deduped: 2607
    conflicts_kept_first: 0