Results and formats

The JSON shape, and how Excel and CSV files are built from it.

A finished job has three downloads. They need no key.

curl -o list.xlsx "https://api.docbeast.com/v1/jobs/job_cbff.../result.xlsx"
curl -o list.csv  "https://api.docbeast.com/v1/jobs/job_cbff.../result.csv"
curl "https://api.docbeast.com/v1/jobs/job_cbff.../result.json"

Excel and CSV files are sent as downloads named after your file. If the job isn't finished, these return 409 not_ready, and once a result has been deleted they return 410 expired.

JSON

{
  "id": "job_cbff845fa8cb4e0a9f3d26b14c7e5a10",
  "filename": "list.pdf",
  "page_count": 2,
  "pages": [
    {
      "page": 1,
      "tables": [{ "rows": [["Part no.", "Pack"], ["00412", "100"]] }],
      "text": "",
      "seconds": 4.2,
      "truncated": false
    },
    {
      "page": 2,
      "tables": [],
      "text": "",
      "seconds": 0,
      "truncated": false,
      "error": "..."
    }
  ]
}

Field	Meaning
`page_count`	Pages in the document.
`pages[].page`	The page number, starting at 1.
`pages[].tables`	The tables found, each as `rows`: an array of rows, each an array of cell strings.
`pages[].text`	Text outside any table. In `text` mode, the page's text.
`pages[].seconds`	How long the page took to read.
`pages[].truncated`	`true` means the page hit a length limit and may be incomplete.
`pages[].error`	Only there when this page couldn't be read. Its `tables` and `text` are empty.

Every cell is a string, so nothing is lost: values like 00412 keep their leading zeros.

Merged cells

Spreadsheets filter and sort better without merged cells, so docbeast unmerges them. A value that covers several rows is repeated on each of those rows. A value that covers several columns stays in the first column, and the other columns are blank.

Excel

The .xlsx file has one sheet for each table, or a sheet of text lines when a page has no table:

Page 1 for a page's only table.
Page 2 table 1, Page 2 table 2 when a page has several.
Page 2 text for text beside a table, or Page 2 for a page with only text.

In table mode, a page with a table returns only that table, so titles, dates and other details around it are left out. Use mode=text when you need those. Text becomes one row per line, split into columns on tabs or runs of two or more spaces.

Plain numbers such as 47,000 or -12.50 become numeric cells. Part numbers with leading zeros, like 00412, and digit runs longer than 15 digits stay as text, so they aren't changed.

CSV

The .csv file has the same sheets one after another, separated by a blank line.

A scan can contain anything, so a cell a spreadsheet would run as a formula gets a leading apostrophe. That covers cells starting with =, +, @, a tab or a return, and cells starting with - that aren't numbers.

Text mode

Use mode=text for documents without tables, such as letters. The result has the page's text in text, and in Excel and CSV each line becomes a row.