Submit a Book

POST /submit-book
Content-Type: multipart/form-data

This endpoint creates a Book, attaches every uploaded file, and starts parsing in the background. The response arrives before parsing finishes. Use one request per deal. Files submitted together are classified and parsed as one package.

Request

files

file[]

required

One or more financial documents. Send multiple files by repeating the files field.

book_name

string

required

A recognizable name for the deal. The parser may later replace it with the extracted business name.

description

string

Optional context stored on the Book.

webhook_url

string

Optional HTTPS URL that receives the final parse status. Omit it when you plan to poll.

PDF is the normal format for bank statements, credit reports, applications, and tax forms. Supported document images can also be classified. Files that cannot be classified remain visible on the Book with a failed or unsupported status.

Example

from pathlib import Path
import requests

API_BASE = "https://api.lendpathway.com/api"
TOKEN = "pat_your_token_here"

paths = [Path("jan.pdf"), Path("feb.pdf"), Path("application.pdf")]

with requests.Session() as session:
    session.headers["Authorization"] = f"Bearer {TOKEN}"

    opened = [path.open("rb") for path in paths]
    try:
        files = [
            ("files", (path.name, handle, "application/pdf"))
            for path, handle in zip(paths, opened)
        ]
        response = session.post(
            f"{API_BASE}/submit-book",
            files=files,
            data={
                "book_name": "Smith Auto Body",
                "webhook_url": "https://example.com/webhooks/pathway",
            },
            timeout=120,
        )
        response.raise_for_status()
        print(response.json())
    finally:
        for handle in opened:
            handle.close()

import { openAsBlob } from "node:fs";

const API_BASE = "https://api.lendpathway.com/api";
const TOKEN = "pat_your_token_here";

const form = new FormData();
form.set("book_name", "Smith Auto Body");
form.set("webhook_url", "https://example.com/webhooks/pathway");

for (const filename of ["jan.pdf", "feb.pdf", "application.pdf"]) {
  const file = await openAsBlob(filename, { type: "application/pdf" });
  form.append("files", file, filename);
}

const response = await fetch(`${API_BASE}/submit-book`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
  body: form,
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

console.log(await response.json());

curl --fail-with-body \
  "https://api.lendpathway.com/api/submit-book" \
  -H "Authorization: Bearer pat_your_token_here" \
  -F "book_name=Smith Auto Body" \
  -F "webhook_url=https://example.com/webhooks/pathway" \
  -F "[email protected];type=application/pdf" \
  -F "[email protected];type=application/pdf" \
  -F "[email protected];type=application/pdf"

Do not set Content-Type manually in Python or JavaScript. The HTTP client adds the multipart boundary when it builds the body.

Response

class SubmitBookResponse(BaseModel):
    book_id: str
    status: str
    message: str

{
  "book_id": "99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78",
  "status": "processing",
  "message": "Processing started"
}

Save book_id. You use it to read status, analytics, exports, and embeds.

status: "processing" confirms that the asynchronous submission flow was accepted. Continue checking the Book until its stored parse_status becomes completed, failed, or cancelled.

Completion webhook

When webhook_url is present, Pathway sends one JSON POST after the parse reaches its final database status.

class ParseWebhook(BaseModel):
    book_id: str
    status: Literal["completed", "failed", "cancelled"]
    book_url: str
    error: str | None = None

{
  "book_id": "99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78",
  "status": "completed",
  "book_url": "https://app.lendpathway.com/books/99cc93e6-1f3f-42b1-9fe4-ba5a95be9c78"
}

Return a 2xx response quickly and move any result fetching into your own background job.

Completion webhooks are currently unsigned and are sent once. Treat the Book ID as a lookup key, then call the authenticated Book endpoint to confirm the current status before moving a deal forward.

Poll instead

Call GET /books/{book_id} every few seconds and stop on a terminal status. The full implementation, including timeouts and failure handling, is in Parse documents and get results.

Common failures

Status	Cause
`401`	Missing or invalid PAT
`403`	Read-only token or insufficient access
`422`	Required multipart fields are missing or malformed
`500`	Pathway could not stage the Book or its documents

Individual file failures and usage-limit checks occur after this request returns. Read the Book and its documents for the final outcome. A usage limit moves the Book to failed and places the reason in parse_status_message.

Overview

Endpoints

Cookbook

Request

Example

Response

Completion webhook

Poll instead

Common failures

​Request

​Example

​Response

​Completion webhook

​Poll instead

​Common failures

Request

Example

Response

Completion webhook

Poll instead

Common failures