Document

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-document-schema.json",
  "title": "Document",
  "description": "**Documents** are the primary way to bring financial data into an Application for analysis.\n\nA document represents a single PDF file containing one or more financial statements relevant to the application.\n\nWhen a document is uploaded to an Application, Akahu Apply will process the information from the document and convert it to a standardised format.\n\nDocuments can be added to an application using the Akahu Apply portal, via API, or by your applicant directly using a Sharing Request.\n\nNote: Documents and their associated data expire 1 year after creation.",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-apply-api-openapi.yml#/components/schemas/Document",
  "type": "object",
  "properties": {
    "_id": {
      "$ref": "#/$defs/DocumentId"
    },
    "_application": {
      "type": "string",
      "pattern": "^application_[a-z0-9]{24,27}$",
      "description": "The application that this document belongs to."
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "The filename of this document."
    },
    "status": {
      "$ref": "#/$defs/DocumentStatus"
    },
    "failure_reason": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/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": "#/$defs/DocumentChannelSharingRequest"
        },
        {
          "$ref": "#/$defs/DocumentChannelApi"
        },
        {
          "$ref": "#/$defs/DocumentChannelPortal"
        },
        {
          "$ref": "#/$defs/DocumentChannelReferral"
        }
      ],
      "description": "The channel that was used to create the document along with any relevant metadata for that channel.\n\nThis field can be used to determine whether the document was created via a Sharing Request, API, or the Akahu Apply portal."
    },
    "source": {
      "oneOf": [
        {
          "$ref": "#/$defs/DocumentSourceDirectUpload"
        },
        {
          "$ref": "#/$defs/DocumentSourceOneoffObConnection"
        }
      ],
      "description": "How the document file was ingested by Akahu Apply.\n\nThis 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": "#/$defs/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"
  ],
  "$defs": {
    "DocumentChannelApi": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "api"
          ]
        }
      },
      "required": [
        "type"
      ],
      "description": "The document was uploaded via API."
    },
    "DocumentChannelPortal": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "portal"
          ]
        }
      },
      "required": [
        "type"
      ],
      "description": "The document was uploaded via the Akahu Apply portal."
    },
    "DocumentChannelReferral": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "referral"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^referral_[a-z0-9]{24,27}$",
          "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": "#/$defs/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."
    },
    "DocumentChannelSharingRequest": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "sharing_request"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^sharing_request_[a-z0-9]{24,27}$",
          "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."
    },
    "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": "#/$defs/DocumentContentRange"
          }
        }
      },
      "required": [
        "page_count",
        "processed_count",
        "skipped_count",
        "unprocessed_count",
        "ranges"
      ]
    },
    "DocumentContentRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "number"
        },
        "end": {
          "type": "number"
        },
        "outcome": {
          "$ref": "#/$defs/DocumentRangeOutcome"
        },
        "inferred_content": {
          "$ref": "#/$defs/DocumentContentType"
        }
      },
      "required": [
        "start",
        "end",
        "outcome",
        "inferred_content"
      ],
      "description": "Describes the processing outcome of a range of pages in a document."
    },
    "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"
    },
    "DocumentFailureReasonCode": {
      "type": "string",
      "enum": [
        "internal_error",
        "invalid_input",
        "password_protected",
        "timeout",
        "malware_scan_failed",
        "malware_detected"
      ]
    },
    "DocumentId": {
      "type": "string",
      "pattern": "^doc_[a-z0-9]{24,27}$"
    },
    "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."
    },
    "DocumentSourceOneoffObConnection": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "oneoff_ob_connection"
          ]
        },
        "_id": {
          "type": "string",
          "pattern": "^oneoff_ob_connection_[a-z0-9]{24,27}$",
          "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."
    },
    "OrgId": {
      "type": "string",
      "pattern": "^org_[a-z0-9]{24,27}$"
    }
  }
}