Akahu Referrals API

openapi: 3.2.0
info:
  title: Akahu Apply Referrals API
  version: 1.0.0
servers:
- url: https://api.apply.akahu.nz
  description: Akahu Apply API
tags:
- name: Referrals
paths:
  /v1/applications/{applicationId}/referrals:
    post:
      operationId: CreateReferral
      tags:
      - Referrals
      summary: Create referral
      description: Create an application snapshot with a code that can be redeemed by another organisation to create a new application with the same data.
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferralParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReferral400ErrorResponse'
        '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: ListReferrals
      tags:
      - Referrals
      summary: List referrals
      description: List the referrals that have been created from an 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/Referral'
                required:
                - items
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListReferrals400ErrorResponse'
        '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}/referrals/{referralId}:
    get:
      operationId: GetReferral
      tags:
      - Referrals
      summary: Get referral
      description: Get the redemption code and expiry for a referral.
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/ReferralId'
        required: true
        name: referralId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReferral400ErrorResponse'
        '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}/referrals/{referralId}/revoke:
    put:
      operationId: RevokeReferral
      tags:
      - Referrals
      summary: Revoke referral
      description: 'Revoke a referral so that its code can no longer be redeemed. Revocation is permanent.


        Organisations that have previously redeemed the referral keep their copies of the application data.'
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ApplicationId'
        required: true
        name: applicationId
        in: path
      - schema:
          $ref: '#/components/schemas/ReferralId'
        required: true
        name: referralId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeReferral400ErrorResponse'
        '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/referral-redemptions:
    post:
      operationId: CreateReferralRedemption
      tags:
      - Referrals
      summary: Redeem referral
      description: 'Redeem a referral code into a new application.


        Referral redemption is asynchronous. The response includes a redemption ID and processing status. Poll `GET /v1/referral-redemptions/{redemptionId}` until the redemption status is `completed` or `failed`. The completed response includes the new application ID.'
      deprecated: false
      security:
      - APIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferralRedemptionParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralRedemption'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReferralRedemption400ErrorResponse'
        '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/referral-redemptions/{redemptionId}:
    get:
      operationId: GetReferralRedemption
      tags:
      - Referrals
      summary: Get redemption status
      description: Get the current status of a referral redemption. Use this endpoint to poll until the status is `completed` or `failed`.
      deprecated: false
      security:
      - APIKey: []
      parameters:
      - schema:
          $ref: '#/components/schemas/ReferralRedemptionId'
        required: true
        name: redemptionId
        in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralRedemption'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReferralRedemption400ErrorResponse'
        '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:
    ReferralOrgDetails:
      type: object
      properties:
        name:
          type: string
        logo:
          type: string
          description: A URL referencing the org's logo in PNG format.
      required:
      - name
      description: Details for an organisation involved in a referral.
    ReferralStatus:
      type: string
      enum:
      - active
      - expired
      - revoked
      description: "The status of a referral:\n\n - `active` The referral code can be redeemed.\n\n - `expired` The referral has passed its expiry and can no longer be redeemed.\n\n - `revoked` The referral has been revoked and can no longer be redeemed."
    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
    GetReferralRedemption400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/GetReferralRedemption400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    GetReferral400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/GetReferral400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    ListReferrals400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/ListReferrals400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    CreateReferralRedemption400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
      - referral_expired
      - referral_revoked
      - report_type_locked
    ReferralRedemption:
      oneOf:
      - $ref: '#/components/schemas/ReferralRedemptionProcessing'
      - $ref: '#/components/schemas/ReferralRedemptionCompleted'
      - $ref: '#/components/schemas/ReferralRedemptionFailed'
      discriminator:
        propertyName: status
        mapping:
          processing: '#/components/schemas/ReferralRedemptionProcessing'
          completed: '#/components/schemas/ReferralRedemptionCompleted'
          failed: '#/components/schemas/ReferralRedemptionFailed'
      description: A redemption of a referral code into a new application owned by the authenticated organisation.
    Generic429ErrorResponseCode:
      type: string
      enum:
      - too_many_requests
    RevokeReferral400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/RevokeReferral400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    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
    ReferralRedemptionFailed:
      type: object
      properties:
        _id:
          type: string
          pattern: ^referral_redemption_[a-z0-9]{24,27}$
          example: referral_redemption_tz4a98xxat96iws9zmbrgj3a
          description: The unique ID of the referral redemption.
        referrer:
          $ref: '#/components/schemas/ReferralOrgDetails'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - failed
        failure_reason:
          $ref: '#/components/schemas/ReferralRedemptionFailureReason'
      required:
      - _id
      - referrer
      - created_at
      - updated_at
      - status
      - failure_reason
    GetReferral400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
    ListReferrals400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
    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
    CreateReferralParams:
      type: object
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 500
          description: Optional default reference to use for applications created from this referral. Defaults to the source application reference.
      default: {}
    ReferralId:
      type: string
      pattern: ^referral_[a-z0-9]{24,27}$
      example: referral_tz4a98xxat96iws9zmbrgj3a
    Referral:
      type: object
      properties:
        _id:
          type: string
          pattern: ^referral_[a-z0-9]{24,27}$
          example: referral_tz4a98xxat96iws9zmbrgj3a
          description: The unique ID of the referral.
        code:
          $ref: '#/components/schemas/ReferralCode'
        status:
          $ref: '#/components/schemas/ReferralStatus'
        reference:
          type: string
          description: The default reference that applications created from this referral will use.
        expires_at:
          type: string
          format: date-time
          description: The time after which the referral code can no longer be redeemed.
        revoked_at:
          type: string
          format: date-time
          description: The time at which the referral was revoked. Only present when `status` is `revoked`.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        redeemed_by:
          type: array
          items:
            $ref: '#/components/schemas/ReferralOrgDetails'
          description: Organisations that have successfully redeemed this referral.
      required:
      - _id
      - code
      - status
      - reference
      - expires_at
      - created_at
      - updated_at
      - redeemed_by
      description: An application snapshot that can be redeemed by another organisation to create a new application with copied resources.
    ReferralRedemptionFailureReasonCode:
      type: string
      enum:
      - document_unavailable
      - internal_error
      description: "The reason for a referral redemption's failure:\n\n - `document_unavailable` One or more referral snapshot artifacts are no longer available.\n\n - `internal_error` An unhandled internal error prevented the redemption from completing."
    ReferralRedemptionCompleted:
      type: object
      properties:
        _id:
          type: string
          pattern: ^referral_redemption_[a-z0-9]{24,27}$
          example: referral_redemption_tz4a98xxat96iws9zmbrgj3a
          description: The unique ID of the referral redemption.
        referrer:
          $ref: '#/components/schemas/ReferralOrgDetails'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        _application:
          type: string
          pattern: ^application_[a-z0-9]{24,27}$
          example: application_tz4a98xxat96iws9zmbrgj3a
          description: The ID of the new application created. Only present when `status` is `completed`.
        status:
          type: string
          enum:
          - completed
      required:
      - _id
      - referrer
      - created_at
      - updated_at
      - _application
      - status
    ReferralRedemptionProcessing:
      type: object
      properties:
        _id:
          type: string
          pattern: ^referral_redemption_[a-z0-9]{24,27}$
          example: referral_redemption_tz4a98xxat96iws9zmbrgj3a
          description: The unique ID of the referral redemption.
        referrer:
          $ref: '#/components/schemas/ReferralOrgDetails'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - processing
      required:
      - _id
      - referrer
      - created_at
      - updated_at
      - status
    ReferralCode:
      type: string
      pattern: ^AK_[A-Z0-9]{10}$
      example: AK_23456789BC
      description: A referral code using the format `AK_` followed by 10 uppercase alphanumeric characters.
    CreateReferralRedemption400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/CreateReferralRedemption400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    GetReferralRedemption400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
    RevokeReferral400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
    Generic401ErrorResponseCode:
      type: string
      enum:
      - unauthorized
    Generic404ErrorResponseCode:
      type: string
      enum:
      - not_found
    Generic500ErrorResponseCode:
      type: string
      enum:
      - internal_error
    ReferralRedemptionId:
      type: string
      pattern: ^referral_redemption_[a-z0-9]{24,27}$
      example: referral_redemption_tz4a98xxat96iws9zmbrgj3a
    ReferralRedemptionFailureReason:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ReferralRedemptionFailureReasonCode'
        message:
          type: string
          default: Sorry, something went wrong while redeeming this referral. Please try again later.
      required:
      - code
      description: If a referral redemption has failed, this field provides additional information about what went wrong.
    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
    CreateReferral400ErrorResponseCode:
      type: string
      enum:
      - feature_disabled
      - referral_no_documents
      - referral_currently_processing
      - referral_document_unavailable
    CreateReferral400ErrorResponse:
      type: object
      properties:
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                oneOf:
                - $ref: '#/components/schemas/Generic400ErrorResponseCode'
                - $ref: '#/components/schemas/CreateReferral400ErrorResponseCode'
              message:
                type: string
              path:
                $ref: '#/components/schemas/IssuePath'
            required:
            - code
            - message
            - path
      required:
      - issues
    Generic403ErrorResponseCode:
      type: string
      enum:
      - forbidden
    IssuePath:
      type: array
      items:
        title: IssuePathSegment
        oneOf:
        - type: string
        - type: integer
    CreateReferralRedemptionParams:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ReferralCode'
        reference:
          type: string
          minLength: 1
          maxLength: 500
          description: Optional reference to use for the application created in the redeeming organisation. Defaults to the referral reference.
        report_type:
          type: string
          enum:
          - standard
          - income
          description: If `report_type` is omitted, the application uses your organisation's default report type.
      required:
      - code
  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