Documents

Documents are uploaded files attached to a deal for processing. The most common document type is a bank statement, but the platform also supports tax returns, P&L statements, and other underwriting documents. Each document goes through an automated pipeline: text extraction, classification, LLM parsing, analysis, and transaction screening.

Processing statuses progress through: uploaded → extracting_text → classifying → parsing_with_llm → analyzing → screening → completed. If any step fails, the status is set to failed with an error message.

Upload

Upload a single document to a deal. The file is sent as multipart form data. Supported formats include PDF, PNG, JPG, and TIFF. The document is automatically queued for processing upon upload.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The deal to attach the document to

Request Body (multipart/form-data)

Name	Type	Required	Description
file	file	Required	The document file. Max 25 MB. Supported formats: PDF, PNG, JPG, TIFF.

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/documents \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@bank_statement_jan_2026.pdf"

Response

Response — 201 Created

{
  "id": 15,
  "deal_id": 42,
  "filename": "bank_statement_jan_2026.pdf",
  "file_size": 245780,
  "mime_type": "application/pdf",
  "document_type": null,
  "status": "uploaded",
  "page_count": 4,
  "created_at": "2026-02-15T14:05:00Z",
  "updated_at": "2026-02-15T14:05:00Z"
}

Upload multiple documents in a single request. Each file is sent as a separate form field. All files are attached to the specified deal and queued for processing. Maximum 25 files per request.

Request Body (multipart/form-data)

Name	Type	Required	Description
deal_id	integer	Required	The deal to attach documents to
files	file[]	Required	One or more document files. Max 25 files, each up to 25 MB.

Example

curl

curl -X POST https://api.banklyze.com/v1/bulk-upload \
  -H "X-API-Key: your_api_key_here" \
  -F "deal_id=42" \
  -F "files=@statement_jan.pdf" \
  -F "files=@statement_feb.pdf" \
  -F "files=@statement_mar.pdf"

Response

Response — 200 OK

{
  "uploaded": [
    {
      "id": 15,
      "filename": "statement_jan.pdf",
      "status": "uploaded"
    },
    {
      "id": 16,
      "filename": "statement_feb.pdf",
      "status": "uploaded"
    },
    {
      "id": 17,
      "filename": "statement_mar.pdf",
      "status": "uploaded"
    }
  ],
  "errors": [],
  "total_uploaded": 3,
  "total_errors": 0
}

Retrieval

Retrieve all documents attached to a deal. Returns summary information including processing status, document type, and key statement metadata for completed documents.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The deal ID

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42/documents \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 15,
      "deal_id": 42,
      "filename": "statement_jan.pdf",
      "file_size": 245780,
      "mime_type": "application/pdf",
      "document_type": "bank_statement",
      "status": "completed",
      "page_count": 4,
      "bank_name": "Chase",
      "account_last_four": "4821",
      "statement_period_start": "2026-01-01",
      "statement_period_end": "2026-01-31",
      "transaction_count": 87,
      "created_at": "2026-02-15T14:05:00Z",
      "updated_at": "2026-02-15T14:08:32Z"
    },
    {
      "id": 16,
      "deal_id": 42,
      "filename": "statement_feb.pdf",
      "file_size": 231400,
      "mime_type": "application/pdf",
      "document_type": "bank_statement",
      "status": "completed",
      "page_count": 3,
      "bank_name": "Chase",
      "account_last_four": "4821",
      "statement_period_start": "2026-02-01",
      "statement_period_end": "2026-02-28",
      "transaction_count": 72,
      "created_at": "2026-02-15T14:05:01Z",
      "updated_at": "2026-02-15T14:09:15Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 3,
    "total_pages": 1
  }
}

Retrieve a single document by ID with full detail including extraction metadata, analysis results, and prescreen flags. This is the most comprehensive view of a processed document.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X GET https://api.banklyze.com/v1/documents/15 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "id": 15,
  "deal_id": 42,
  "filename": "statement_jan.pdf",
  "file_size": 245780,
  "mime_type": "application/pdf",
  "document_type": "bank_statement",
  "status": "completed",
  "page_count": 4,
  "bank_name": "Chase",
  "account_last_four": "4821",
  "statement_period_start": "2026-01-01",
  "statement_period_end": "2026-01-31",
  "transaction_count": 87,
  "extraction": {
    "method": "llm",
    "model": "claude-haiku-4-5",
    "confidence": 0.96,
    "extracted_at": "2026-02-15T14:06:12Z"
  },
  "analysis": {
    "total_deposits": 125430.00,
    "total_withdrawals": 112840.00,
    "avg_daily_balance": 34500.00,
    "ending_balance": 41200.00,
    "nsf_count": 1,
    "overdraft_count": 0,
    "deposit_count": 34,
    "screening_flags": 2,
    "analyzed_at": "2026-02-15T14:07:45Z"
  },
  "prescreen": {
    "flagged_transactions": 2,
    "buckets": {
      "large_unusual_deposit": 1,
      "repeat_charge": 1
    }
  },
  "created_at": "2026-02-15T14:05:00Z",
  "updated_at": "2026-02-15T14:08:32Z"
}

Check the current processing status of a document. Returns the current step and timestamps for all completed steps. Use this endpoint to poll for processing completion or to display a progress indicator.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X GET https://api.banklyze.com/v1/documents/15/status \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "id": 15,
  "status": "completed",
  "steps": [
    { "name": "uploaded", "completed_at": "2026-02-15T14:05:00Z" },
    { "name": "extracting_text", "completed_at": "2026-02-15T14:05:18Z" },
    { "name": "classifying", "completed_at": "2026-02-15T14:05:22Z" },
    { "name": "parsing_with_llm", "completed_at": "2026-02-15T14:06:12Z" },
    { "name": "analyzing", "completed_at": "2026-02-15T14:07:45Z" },
    { "name": "screening", "completed_at": "2026-02-15T14:08:30Z" },
    { "name": "completed", "completed_at": "2026-02-15T14:08:32Z" }
  ],
  "error": null
}

Processing Actions

Re-queue a document for processing from the beginning. This is typically used to retry a document that failed during processing due to a transient error. The document status is reset to uploaded and the full pipeline runs again.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X POST https://api.banklyze.com/v1/documents/15/reprocess \
  -H "X-API-Key: your_api_key_here"

Response

Response — 202 Accepted

{
  "status": "ok",
  "message": "Document queued for reprocessing",
  "document_id": 15
}

Override the automatic document classification and assign a new document type. The document is then reprocessed through the appropriate type-specific pipeline. Use this when the auto-classifier misidentified a document (e.g., classified a bank statement as a tax return).

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Request Body

Name	Type	Required	Description
document_type	string	Required	The correct document type: bank_statement, tax_return, pnl_statement, other

Example

curl

curl -X POST https://api.banklyze.com/v1/documents/15/reclassify \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"document_type": "bank_statement"}'

Response

Response — 200 OK

{
  "status": "ok",
  "message": "Document reclassified and queued for reprocessing",
  "document_id": 15,
  "document_type": "bank_statement"
}

Cancel an in-progress document processing job. The document status is set to failed with a cancellation reason. This is useful if you uploaded the wrong file and want to stop processing before it completes.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X POST https://api.banklyze.com/v1/documents/15/cancel \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "status": "ok",
  "message": "Document processing cancelled",
  "document_id": 15
}

Data Access

Retrieve the raw extraction results from the OCR and LLM parsing step. This includes the detected bank name, account details, statement period, and metadata about the extraction method and confidence score.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X GET https://api.banklyze.com/v1/documents/15/extraction \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "document_id": 15,
  "method": "llm",
  "model": "claude-haiku-4-5",
  "confidence": 0.96,
  "bank_name": "Chase",
  "account_number_last_four": "4821",
  "account_holder": "Acme Trucking LLC",
  "statement_period_start": "2026-01-01",
  "statement_period_end": "2026-01-31",
  "opening_balance": 28500.00,
  "closing_balance": 41200.00,
  "transaction_count": 87,
  "raw_text_pages": 4,
  "extracted_at": "2026-02-15T14:06:12Z"
}

Retrieve the computed analysis for a processed document. This includes aggregate financial metrics, NSF/overdraft counts, deposit statistics, and transaction screening results. Analysis data is only available after the document reaches completed status.

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Example

curl

curl -X GET https://api.banklyze.com/v1/documents/15/analysis \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "document_id": 15,
  "total_deposits": 125430.00,
  "total_withdrawals": 112840.00,
  "net_cash_flow": 12590.00,
  "avg_daily_balance": 34500.00,
  "min_daily_balance": 8200.00,
  "max_daily_balance": 62400.00,
  "ending_balance": 41200.00,
  "deposit_count": 34,
  "withdrawal_count": 53,
  "nsf_count": 1,
  "nsf_total_fees": 36.00,
  "overdraft_count": 0,
  "overdraft_total_fees": 0.00,
  "deposit_frequency_per_month": 34,
  "avg_deposit_amount": 3689.12,
  "largest_deposit": 18500.00,
  "screening_flags": 2,
  "screening_buckets": {
    "large_unusual_deposit": 1,
    "repeat_charge": 1
  },
  "analyzed_at": "2026-02-15T14:07:45Z"
}

Check the processing status of multiple documents in a single request. This is more efficient than polling individual document status endpoints when you need to track progress across a batch upload.

Request Body

Name	Type	Required	Description
document_ids	integer[]	Required	Array of document IDs to check. Maximum 100 IDs per request.

Example

curl

curl -X POST https://api.banklyze.com/v1/documents/batch-status \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": [15, 16, 17]}'

Response

Response — 200 OK

{
  "statuses": [
    {
      "id": 15,
      "status": "completed",
      "document_type": "bank_statement",
      "error": null
    },
    {
      "id": 16,
      "status": "completed",
      "document_type": "bank_statement",
      "error": null
    },
    {
      "id": 17,
      "status": "analyzing",
      "document_type": "bank_statement",
      "error": null
    }
  ]
}

Deals

Transactions