Akahu Sharing Requests API

openapi: 3.2.0
info:
  title: Akahu Apply Sharing Requests API
  version: 1.0.0
servers:
- url: https://api.apply.akahu.nz
  description: Akahu Apply API
tags:
- name: Sharing Requests
paths:
  /v1/applications/{applicationId}/sharing-request:
    post:
      operationId: CreateSharingRequest
      tags:
      - Sharing Requests
      summary: Create sharing request
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSharingRequestParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharingRequest'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSharingRequest400ErrorResponse'
        '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}/sharing-request/{sharingRequestId}:
    get:
      operationId: GetSharingRequest
      tags:
      - Sharing Requests
      summary: Get a sharing request
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/SharingRequestId'
        required: true
        name: sharingRequestId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharingRequest'
        '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:
    SharingRequestInstitutionStub:
      type: string
      enum:
      - amex
      - anz
      - asb
      - bnz
      - coop
      - heartland
      - kiwibank
      - latitude
      - sbs
      - tsb
      - westpac
    SharingRequestRedirectUri:
      type: string
      format: uri
      description: 'The https uri to redirect to after the sharing request is used. This can contain query parameters, e.g. for passing state.


        This is optional and can be used to redirect the user to a specific page after they have successfully connected their accounts. If not provided, the user will be told that they can close the page.


        If the user cancels the flow without adding any statements, they will be redirected to this uri with the query parameters `applicationId={applicationId}&sharingRequestId={sharingRequestId}&action=cancelled`.


        If the user adds any statements, they will be redirected to this uri with the query parameters `applicationId={applicationId}&sharingRequestId={sharingRequestId}&action=submitted`.'
    CreateSharingRequest400ErrorResponseCode:
      type: string
      enum:
      - application_archived
    Generic429ErrorResponseCode:
      type: string
      enum:
      - too_many_requests
    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
    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
    SharingRequest:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/SharingRequestId'
        link:
          type: string
          format: uri
          description: A URL to the Akahu Apply applicant sharing portal.
        created_at:
          type: string
          format: date-time
          description: The date that this sharing request was created.
        expires_at:
          type: string
          format: date-time
          description: The date that this sharing request will expire.
        last_submitted_at:
          type: string
          format: date-time
          description: The date that the applicant last submitted data through this sharing request.
      required:
      - _id
      - link
      - created_at
      - expires_at
      description: 'You can invite your applicant to provide financial data for their Application by creating a Sharing Request. Each Sharing Request is associated with a specific Application, and you can create multiple Sharing Requests per Application.


        Using a Sharing Request, you can send your applicant to an Akahu Apply web page where they will be guided through the process of sharing the requested financial data. Any Resources created by the applicant during this process will automatically be attached to the associated Application.'
    Generic401ErrorResponseCode:
      type: string
      enum:
      - unauthorized
    Generic500ErrorResponseCode:
      type: string
      enum:
      - internal_error
    Generic404ErrorResponseCode:
      type: string
      enum:
      - not_found
    CreateSharingRequestParams:
      type: object
      properties:
        requested_days:
          type: integer
          minimum: 30
          maximum: 730
          description: How much historical data (i.e. bank statements) will be requested of the applicant. This is applied at the time the applicant completes the request.
        expires_in_days:
          type: integer
          minimum: 7
          maximum: 60
          default: 30
          description: 'The number of days from creation until this sharing request expires. Must be between 7 and 60 days.


            Defaults to 30 days when not provided.'
        allow_manual_uploads:
          type: boolean
          description: Determines whether the applicant is given the option to supply data manually by uploading PDF documents.
        skip_landing_page:
          type: boolean
          default: false
          description: 'Skips the sharing request landing page and navigates the applicant directly to the open banking flow.


            `allow_manual_uploads` must be set to `false` to change the default value of this parameter.'
        allow_multiple_submissions:
          type: boolean
          description: 'Determines whether the applicant is allowed to submit more data if they return to the sharing request URL after submission.


            Defaults to the same value as `allow_multiple_ob_connections`.'
        allow_multiple_ob_connections:
          type: boolean
          default: true
          description: 'Determines whether the applicant is allowed to complete multiple open banking connections as part of this sharing request.

            If set to `false`, the sharing request will submit automatically upon successful completion of an open banking connection.


            `allow_manual_uploads` must be set to `false` to change the default value of this parameter.'
        ob_connection_filter:
          type: array
          items:
            $ref: '#/components/schemas/SharingRequestInstitutionStub'
          minItems: 1
          maxItems: 1
          description: 'Optionally restricts which institutions are available for connection via open banking.

            This setting does not restrict the applicant''s ability to upload documents from other institutions using the manual upload feature (if enabled).


            Note: This parameter currently accepts only a single value.'
        redirect_uri:
          $ref: '#/components/schemas/SharingRequestRedirectUri'
      required:
      - requested_days
      - allow_manual_uploads
    SharingRequestId:
      type: string
      pattern: ^sharing_request_[a-z0-9]{24,27}$
      example: sharing_request_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
    CreateSharingRequest400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/CreateSharingRequest400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    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
  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