Akahu Documents API

openapi: 3.2.0
info:
  title: Akahu Apply Documents API
  version: 1.0.0
servers:
- url: https://api.apply.akahu.nz
  description: Akahu Apply API
tags:
- name: Documents
paths:
  /v1/applications/{applicationId}/documents:
    post:
      operationId: CreateDocument
      tags:
      - Documents
      summary: Create document
      description: 'This endpoint creates a new document record in a `pending` state.

        Each document represents a single file, which needs to be uploaded shortly after document creation.


        If the document file is not uploaded before the `expires_at` timestamp included in the response, the record will be automatically deleted.


        The document file can be uploaded by making a `PUT` request to the `upload_url` provided in the response.

        Document uploads must meet the following criteria:


        - Files have a maximum size of 50MB


        - Files must have a `content-type` of ''application/pdf'''
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: The filename of this document.
              required:
              - name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/DocumentId'
                  expires_at:
                    type: string
                    format: date-time
                  upload_url:
                    type: string
                    format: uri
                required:
                - _id
                - expires_at
                - upload_url
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDocument400ErrorResponse'
        '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'
    get:
      operationId: ListDocuments
      tags:
      - Documents
      summary: List documents for application
      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/Document'
                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'
  /v1/applications/{applicationId}/documents/{documentId}:
    get:
      operationId: GetDocument
      tags:
      - Documents
      summary: Get document details
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
        name: documentId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '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'
    delete:
      operationId: DeleteDocument
      tags:
      - Documents
      summary: Delete document
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
        name: documentId
        in: path
      responses:
        '204':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocument400ErrorResponse'
        '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'
  /v1/applications/{applicationId}/documents/{documentId}/download:
    get:
      operationId: DownloadDocument
      tags:
      - Documents
      summary: Download document
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
        name: documentId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/pdf:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadDocument400ErrorResponse'
        '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.
    DocumentStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - failed
      description: "The status of a document:\n\n - `pending` The document record exists, but the file has not yet been fully uploaded.\n\n - `processing` Akahu Apply is extracting and enriching the data from this document.\n\n - `completed` This document has been successfully processed.\n\n - `failed` This document has not been successfully processed. See the `failure_reason` for more detail."
    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
    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."
    DocumentSourceDirectUpload:
      type: object
      properties:
        type:
          type: string
          enum:
          - direct_upload
      required:
      - type
      description: The documented was uploaded to Akahu Apply from an external source.
    DocumentChannelApi:
      type: object
      properties:
        type:
          type: string
          enum:
          - api
      required:
      - type
      description: The document was uploaded via API.
    CreateDocument400ErrorResponseCode:
      type: string
      enum:
      - application_archived
    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
    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
    CreateDocument400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/CreateDocument400ErrorResponseCode'
              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
    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
    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.
    DeleteDocument400ErrorResponseCode:
      type: string
      enum:
      - application_archived
    Document:
      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.
        name:
          type: string
          maxLength: 255
          description: The filename of this document.
        status:
          $ref: '#/components/schemas/DocumentStatus'
        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
      - name
      - status
      - channel
      - source
      - created_at
      - updated_at
      description: '**Documents** are the primary way to bring financial data into an Application for analysis.


        A document represents a single PDF file containing one or more financial statements relevant to the application.


        When a document is uploaded to an Application, Akahu Apply will process the information from the document and convert it to a standardised format.


        Documents can be added to an application using the Akahu Apply portal, via API, or by your applicant directly using a Sharing Request.


        Note: Documents and their associated data expire 1 year after creation.'
    DownloadDocument400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/DownloadDocument400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    Generic401ErrorResponseCode:
      type: string
      enum:
      - unauthorized
    Generic500ErrorResponseCode:
      type: string
      enum:
      - internal_error
    Generic404ErrorResponseCode:
      type: string
      enum:
      - not_found
    DownloadDocument400ErrorResponseCode:
      type: string
      enum:
      - document_locked
    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
    DeleteDocument400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/DeleteDocument400ErrorResponseCode'
              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
    Generic403ErrorResponseCode:
      type: string
      enum:
      - forbidden
    IssuePath:
      type: array
      items:
        title: IssuePathSegment
        oneOf:
        - type: string
        - type: integer
  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