Bulk Ingest

The ingest endpoint lets you upload multiple documents at once with automatic deal matching. A single POST /ingest call accepts up to 20 PDF files, creates or matches an existing deal using the provided metadata, and starts processing all documents in parallel. Use the returned batch_id to poll progress or listen to the document.completed webhook event for each file.

If a deal_id is provided in metadata, the documents are attached to that existing deal. If an external_reference is provided, Banklyze will look up any existing deal with that reference before creating a new one. Otherwise, a new deal is created using business_name and optional fields from the metadata object.

Upload one or more PDF files using multipart/form-data. The metadata field is a JSON string that controls deal matching, optional labels, and a callback URL for delivery confirmation. All documents in the batch are enqueued for processing immediately after upload.

Headers

Name	Type	Required	Description
X-Org-Id	integer	Required	Your organization ID. Required for all ingest requests.
Idempotency-Key	string	Optional	A unique key (max 128 characters) to make the request idempotent. Duplicate requests with the same key within 24 hours return the original response without creating a second batch.

Form Parameters

Name	Type	Required	Description
files	file[]	Required	PDF files to upload. Repeat this field for each file. Maximum 20 files and 20 MB per file.
metadata	string (JSON)	Optional	JSON-encoded object controlling deal matching and processing options. See metadata fields below.

Metadata Fields

Name	Type	Required	Description
business_name	string	Optional	Legal business name for deal creation. Required when deal_id and external_reference are not provided.
ein	string	Optional	9-digit Employer Identification Number (digits only). Used as a secondary match key.
deal_id	integer	Optional	Attach documents to an existing deal. If provided, all other deal-creation fields are ignored.
external_reference	string	Optional	Your system's identifier for this deal (e.g. a CRM opportunity ID). Banklyze will look up an existing deal with this reference before creating a new one.
callback_url	string	Optional	URL to POST a completion notification to when all documents in the batch have finished processing. Must be a publicly reachable HTTPS endpoint.
file_labels	string[]	Optional	Human-readable labels for each uploaded file, in the same order as the files array. Labels appear in the document list and deal report.

Example

curl

curl -X POST https://api.banklyze.com/v1/ingest \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Org-Id: 7" \
  -H "Idempotency-Key: batch-2026-03-04-acme" \
  -F "files=@statement_jan.pdf" \
  -F "files=@statement_feb.pdf" \
  -F "files=@statement_mar.pdf" \
  -F 'metadata={"business_name":"Acme Trucking LLC","ein":"123456789","callback_url":"https://your-app.com/webhooks/banklyze","file_labels":["January 2026","February 2026","March 2026"]}'

Response

Response — 202 Accepted

{
  "batch_id": "batch_3f8a2c1d",
  "deal_id": 42,
  "documents": [
    {
      "id": 15,
      "filename": "statement_jan.pdf",
      "label": "January 2026",
      "status": "uploaded"
    },
    {
      "id": 16,
      "filename": "statement_feb.pdf",
      "label": "February 2026",
      "status": "uploaded"
    },
    {
      "id": 17,
      "filename": "statement_mar.pdf",
      "label": "March 2026",
      "status": "uploaded"
    }
  ],
  "created_at": "2026-03-04T11:00:00Z"
}

Poll the processing status of an ingest batch. The top-level status is pending while no documents have started, processing while at least one document is still in flight, and completed once all documents have reached a terminal state (completed or failed). The completed_at timestamp is set when the batch reaches completed.

Path Parameters

Name	Type	Required	Description
batch_id	string	Required	The batch ID returned from POST /ingest

Example

curl

curl -X GET https://api.banklyze.com/v1/ingest/batch_3f8a2c1d \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Org-Id: 7"

Response

Response — 200 OK

{
  "batch_id": "batch_3f8a2c1d",
  "deal_id": 42,
  "status": "processing",
  "total": 3,
  "processed": 2,
  "failed": 0,
  "documents": [
    {
      "id": 15,
      "filename": "statement_jan.pdf",
      "label": "January 2026",
      "status": "completed",
      "processing_completed_at": "2026-03-04T11:02:31Z"
    },
    {
      "id": 16,
      "filename": "statement_feb.pdf",
      "label": "February 2026",
      "status": "completed",
      "processing_completed_at": "2026-03-04T11:02:44Z"
    },
    {
      "id": 17,
      "filename": "statement_mar.pdf",
      "label": "March 2026",
      "status": "parsing_with_llm",
      "processing_completed_at": null
    }
  ],
  "created_at": "2026-03-04T11:00:00Z",
  "completed_at": null
}