Documents

Documents represent uploaded PDF financial files attached to an underwriting deal. Supported document types are bank_statement, tax_return, and profit_and_loss. Banklyze automatically classifies the document type on upload when one is not provided.

Once uploaded, each document moves through the processing pipeline: uploaded → classifying → extracting_text → running_ocr → parsing_with_llm → computing_metrics → completed. A document that cannot be processed will transition to failed. Documents that are cancelled while in-flight transition to cancelled. Poll GET /documents/{document_id}/status or listen to the document.completed webhook event to know when processing is done.

Upload a single PDF document to an existing deal. The file is stored in object storage and the processing pipeline is started asynchronously. Use multipart/form-data encoding. An optional document_type hint can be provided; if omitted, the classifier will detect the type automatically.

Path Parameters

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

Form Parameters

Name	Type	Required	Description
file	file	Required	PDF file to upload. Maximum size 20 MB.
document_type	string	Optional	Optional type hint: bank_statement, tax_return, or profit_and_loss. If omitted, the type is detected automatically.

Example

curl

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

Response

Response — 201 Created

{
  "id": 15,
  "filename": "bank_statement.pdf",
  "status": "uploaded",
  "message": "Document uploaded and processing started"
}

Upload multiple PDF documents to a deal in a single request using multipart/form-data. Repeat the files field for each file. Each file is enqueued for processing independently. Partial failures are reported in the errors array — valid files are still uploaded even when some fail validation.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID to attach the documents to

Form Parameters

Name	Type	Required	Description
files	file[]	Required	PDF files to upload. Repeat this field for each file. Maximum 20 MB per file.

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/documents/bulk \
  -H "X-API-Key: your_api_key_here" \
  -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
}

Retrieve a paginated list of all documents attached to a deal, including their current processing status and basic metadata.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 25	Results per page (max 100)

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,
      "filename": "statement_jan.pdf",
      "document_type": "bank_statement",
      "status": "completed",
      "page_count": 8,
      "created_at": "2026-02-15T14:00:00Z",
      "updated_at": "2026-02-15T14:02:31Z"
    },
    {
      "id": 16,
      "filename": "statement_feb.pdf",
      "document_type": "bank_statement",
      "status": "completed",
      "page_count": 7,
      "created_at": "2026-02-15T14:00:05Z",
      "updated_at": "2026-02-15T14:02:44Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1
  }
}

Retrieve a single document by ID with complete metadata, extraction results, and analysis output. The analysis object is only populated once the document has reached 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 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "id": 15,
  "deal_id": 42,
  "filename": "bank_statement.pdf",
  "document_type": "bank_statement",
  "classification_confidence": 0.97,
  "bank_name": "Chase Bank",
  "account_number_last4": "4821",
  "account_type": "business_checking",
  "statement_start_date": "2026-01-01",
  "statement_end_date": "2026-01-31",
  "opening_balance": 28400.00,
  "closing_balance": 41200.00,
  "status": "completed",
  "extraction_method": "pdfplumber",
  "extraction_confidence": 0.94,
  "pdf_risk_level": "low",
  "page_count": 8,
  "uploaded_at": "2026-02-15T14:00:00Z",
  "processing_started_at": "2026-02-15T14:00:01Z",
  "processing_completed_at": "2026-02-15T14:02:31Z",
  "analysis": {
    "total_credits": 18750.00,
    "total_debits": 5950.00,
    "transaction_count": 47,
    "nsf_count": 0,
    "overdraft_count": 0,
    "avg_daily_balance": 34500.00,
    "deposit_days": 12
  }
}

Lightweight endpoint for polling the current processing status of a document. Returns the status, a human-readable description of the current pipeline step, and an estimated progress percentage. Prefer the document.completed webhook event over polling in production integrations.

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": "parsing_with_llm",
  "processing_step": "Extracting transactions with AI",
  "progress_pct": 65,
  "updated_at": "2026-02-15T14:01:44Z"
}

Reprocessing & Management

Failed or cancelled documents can be requeued for processing without re-uploading the original file. Documents can also be reclassified to correct an incorrect auto-detected type, which automatically triggers reprocessing through the appropriate pipeline.

Requeue a single document for processing. Only documents in failed or cancelled status can be reprocessed. The document status resets to uploaded and the full pipeline runs again from the beginning.

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 reprocessing queued",
  "document_id": 15
}

Requeue all documents with failed or cancelled status within a deal in one call. Useful for recovering from transient processing errors without having to identify and reprocess individual documents.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/reprocess-failed \
  -H "X-API-Key: your_api_key_here"

Response

Response — 202 Accepted

{
  "status": "ok",
  "message": "Reprocessing queued for 2 failed document(s)",
  "queued_document_ids": [18, 19]
}

Override the classified document type and trigger reprocessing through the correct pipeline. Use this when auto-classification assigns the wrong type. The document must not be actively processing (i.e. it must be in completed, failed, or cancelled status).

Path Parameters

Name	Type	Required	Description
document_id	integer	Required	The unique document ID

Query Parameters

Name	Type	Required	Description
document_type	string	Required	The correct document type: bank_statement, tax_return, or profit_and_loss

Example

curl

curl -X POST "https://api.banklyze.com/v1/documents/15/reclassify?document_type=tax_return" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 202 Accepted

{
  "status": "ok",
  "message": "Document reclassified and reprocessing queued",
  "document_id": 15,
  "new_document_type": "tax_return"
}

Cancel a document that is currently being processed. The document transitions to cancelled status. Already-completed documents cannot be cancelled. A cancelled document can be requeued via POST /documents/{document_id}/reprocess.

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
}

Batch & Download

Retrieve the current processing status for up to 100 documents in a single request. This is more efficient than polling individual status endpoints when monitoring a large bulk upload.

Request Body

Name	Type	Required	Description
document_ids	integer[]	Required	Array of document IDs to query. 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

{
  "documents": [
    { "id": 15, "status": "completed", "updated_at": "2026-02-15T14:02:31Z" },
    { "id": 16, "status": "completed", "updated_at": "2026-02-15T14:02:44Z" },
    { "id": 17, "status": "extracting_text", "updated_at": "2026-02-15T14:01:10Z" }
  ]
}

Stream the original uploaded PDF file for a document. The response body is the raw binary PDF with a Content-Type: application/pdf header and a Content-Disposition header set to the original filename. The pre-signed download URL expires after 60 seconds.

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/pdf \
  -H "X-API-Key: your_api_key_here" \
  --output bank_statement.pdf