Skip to main content
When you classify a document with the API, the results are returned in a structured JSON format.

​
Example Response

The following example shows a classification response for a nine-page document containing bank statements and pay stubs: 
{
  "classification": [
    {
      "class": "bank statement",
      "reason": "Checking account statement for Sarah J. Mitchell from Builder's Bank for the period of September 1 to September 30, 2025.",
      "suggested_class": null,
      "page": 0
    },
    {
      "class": "bank statement",
      "reason": "Continuation of the transaction history and account summary for the September 2025 bank statement.",
      "suggested_class": null,
      "page": 1
    },
    {
      "class": "bank statement",
      "reason": "Checking account statement for Sarah J. Mitchell from Builder's Bank for the period of October 1 to October 31, 2025.",
      "suggested_class": null,
      "page": 2
    },
    {
      "class": "bank statement",
      "reason": "Continuation of the transaction history and account summary for the October 2025 bank statement.",
      "suggested_class": null,
      "page": 3
    },
    {
      "class": "bank statement",
      "reason": "Informational page containing bank policies, fraud protection details, and contact information.",
      "suggested_class": null,
      "page": 4
    },
    {
      "class": "pay stub",
      "reason": "Earnings statement from Acme Corporation for Sarah J. Mitchell for the pay period ending August 31, 2025.",
      "suggested_class": null,
      "page": 5
    },
    {
      "class": "pay stub",
      "reason": "Summary of gross pay, deductions, and net pay for the Acme Corporation earnings statement.",
      "suggested_class": null,
      "page": 6
    },
    {
      "class": "pay stub",
      "reason": "Earnings statement from Acme Corporation for Sarah J. Mitchell for the pay period ending September 15, 2025.",
      "suggested_class": null,
      "page": 7
    },
    {
      "class": "pay stub",
      "reason": "Summary of gross pay, deductions, and net pay for the second Acme Corporation earnings statement.",
      "suggested_class": null,
      "page": 8
    }
  ],
  "metadata": {
    "filename": "SarahMitchell-loan-docs.pdf",
    "org_id": "f6t71a157bx9",
    "page_count": 9,
    "duration_ms": 10865,
    "credit_usage": 4.5,
    "job_id": "c19ab8c311db41b391c50a56a4cdea5c",
    "version": "classify-20260420"
  }
}

​
Response Structure

The response contains the following top-level fields:
FieldTypeDescription
classificationarrayPer-page classification results.
metadataobjectProcessing information including credit usage, duration, and page count.

​
Per-Page Results (classification)

The classification field contains an array of results, one per page in the document. Each object includes:
FieldTypeDescription
pagenumberThe page number (0-indexed).
classstringThe class label assigned to this page (for example, "Invoice"). When a page cannot be confidently classified, this value is unknown.
reasonstringAn explanation of why this class was assigned. Use this to understand the classification decision and refine your class list if needed.
suggested_classstring | nullThe closest matching class when class is unknown; otherwise null.

​
Unknown Pages

When a page cannot be confidently classified into any of the classes you defined, the API returns unknown in the class field and a value in suggested_class. Use this to review borderline pages or adjust your class list.

​
Processing Metadata (metadata)

The metadata field provides information about the classification process:
FieldTypeDescription
filenamestringThe name of the input document.
org_idstringOrganization identifier.
page_countnumberTotal number of pages in the document.
duration_msnumberProcessing time in milliseconds.
credit_usagenumberNumber of credits consumed.
job_idstringUnique identifier for the classification job.
versionstringThe model version used for classification.