Multi-page financial report

The job

You receive a 60-page annual report as a PDF. You want the reporting period, total revenue and the auditor’s opinion as fields, the revenue-by-segment table as rows, and a reading of the key chart, without anyone paging through the file.

Sample input

annual-report-2025.pdf, 60 pages:

Pages 1–4: cover with the company logo, contents, and the chair’s letter with a signature.
Pages 5–18: narrative sections with photos of sites and products, and a bar chart of revenue by quarter.
Pages 19–44: financial statements. Dense tables with multi-level column headers (current year, prior year, and change, under each segment), subtotals, and footnote markers that point to notes at the foot of the page.
Pages 45–56: notes to the accounts, mostly paragraphs and small tables.
Pages 57–60: the independent auditor’s report, scanned from paper, with a signature and the firm’s stamp.

Every page carries a running header with the company name and a footer with the page number.

How fileScout processes it

Illustrative: the element breakdown is internal; the API returns the structured values.

fileScout reads the file as a set of elements and handles each kind on its own path, all within the same file:

Element type	Example in this report	How fileScout handles it
`heading`	”Consolidated income statement”	Gives structure to the content beneath it.
`paragraph`	The chair’s letter, the notes to the accounts	Read as text; labelled values in it become fields.
`table`	Revenue by segment, with multi-level headers and subtotals	Read as a table and returned as rows of named columns.
`list`	Key risks in a bulleted list	Read as text; each labelled value becomes a field.
`form_field`	”Reporting period: 1 January to 31 December 2025”	A label and its value, returned as a field.
`graph`	Bar chart of revenue by quarter	A visual element: described as one field (chart type, axes, series). If the same figures also appear as a printed table, both are kept.
`image`	Site and product photos	A visual element: described as one field.
`logo`	Company logo on the cover	A visual element: described as one field.
`signature`	Chair’s and auditor’s signatures	A visual element: who signed, and whether it is dated.
`handwriting`	A handwritten initial on a scanned page	A visual element: the transcribed text.
`stamp`	The audit firm’s stamp	A visual element: described as one field.
`qr_code`	A QR code linking to the online report	A visual element: described as one field.
`other`	Anything that fits none of the above	Read as text.

Running headers and footers, such as the company name and page numbers on every page, carry no data. fileScout skips them, so they cost no tokens. Long files like this one are read in chunks; spreadsheets take a separate path of their own. The fields you get back are the ones your AI Schema defines. The breakdown above is how fileScout finds them; it is not part of the response.

Steps

The cURL commands use two environment variables:

export FILEAI_API_KEY="your-api-key"
export FILEAI_BASE_URL="https://api.orion.file.ai/prod/v1"   # or your regional host

See Regions for regional hosts.

Request an upload URL

Send the file name, its MIME type in fileType, and enabledProducts: ["FILE_SCOUT"]. fileScout needs normal processing, so leave storageOnly out. See Choose products for the rules.

curl -X POST "$FILEAI_BASE_URL/files/upload" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "annual-report-2025.pdf",
    "fileType": "application/pdf",
    "enabledProducts": ["FILE_SCOUT"]
  }'

import os, time, requests

BASE = "https://api.orion.file.ai/prod/v1"
HEADERS = {"x-api-key": os.environ["FILEAI_API_KEY"]}

upload = requests.post(
    f"{BASE}/files/upload",
    headers=HEADERS,
    json={
        "fileName": "annual-report-2025.pdf",
        "fileType": "application/pdf",
        "enabledProducts": ["FILE_SCOUT"],
    },
)
upload.raise_for_status()
upload = upload.json()

import { readFile } from "node:fs/promises";

const BASE = "https://api.orion.file.ai/prod/v1";
const headers = { "x-api-key": process.env.FILEAI_API_KEY };

const upload = await fetch(`${BASE}/files/upload`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    fileName: "annual-report-2025.pdf",
    fileType: "application/pdf",
    enabledProducts: ["FILE_SCOUT"],
  }),
}).then((r) => r.json());

Keep uploadId and presignedUploadURL from the response. enabledProducts works only on this single upload route and in workspaces enabled for it; otherwise the request returns 422.

PUT the file

The URL is valid for 300 seconds. Send the same Content-Type you gave as fileType.

curl -X PUT "<presignedUploadURL>" \
  -H "Content-Type: application/pdf" \
  --data-binary @annual-report-2025.pdf

with open("annual-report-2025.pdf", "rb") as f:
    requests.put(
        upload["presignedUploadURL"],
        data=f,
        headers={"Content-Type": "application/pdf"},
    ).raise_for_status()

await fetch(upload.presignedUploadURL, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: await readFile("annual-report-2025.pdf"),
});

Wait for processing

Poll GET /v1/uploads/{uploadId} until every entry in files is processed or action_required, or wait for a processing callback. A 60-page file takes longer than a one-page invoice, so poll patiently.

curl "$FILEAI_BASE_URL/uploads/<uploadId>" \
  -H "x-api-key: $FILEAI_API_KEY"

while True:
    status = requests.get(f"{BASE}/uploads/{upload['uploadId']}", headers=HEADERS).json()
    if any(s["step"] == "processing_failed" for s in status.get("statuses", [])):
        raise RuntimeError("processing failed")
    files = status.get("files", [])
    if files and all(f["status"] in ("processed", "action_required") for f in files):
        break
    time.sleep(10)

file_id = files[0]["fileId"]

let status;
while (true) {
  status = await fetch(`${BASE}/uploads/${upload.uploadId}`, { headers }).then((r) => r.json());
  if ((status.statuses ?? []).some((s) => s.step === "processing_failed")) throw new Error("processing failed");
  const files = status.files ?? [];
  if (files.length && files.every((f) => ["processed", "action_required"].includes(f.status))) break;
  await new Promise((r) => setTimeout(r, 10000));
}

const fileId = status.files[0].fileId;

The report is one document, so files has one entry. If you upload with isSplit: true, one file can become several documents; iterate over files in that case.

Read the values, with every table row

Pass includeFullTableData=true so tables over 100 rows come back whole.

curl "$FILEAI_BASE_URL/files/<fileId>/values?includeFullTableData=true" \
  -H "x-api-key: $FILEAI_API_KEY"

values = requests.get(
    f"{BASE}/files/{file_id}/values",
    headers=HEADERS,
    params={"includeFullTableData": "true"},
).json()

form = values["formValues"][0]
fields = {f["title"]: f for f in form["fields"]}
segments = [
    {cell["title"]: cell["value"] for cell in row}
    for row in fields["Revenue by segment"]["valueArray"]
]

const values = await fetch(
  `${BASE}/files/${fileId}/values?includeFullTableData=true`,
  { headers },
).then((r) => r.json());

const form = values.formValues[0];
const fields = Object.fromEntries(form.fields.map((f) => [f.title, f]));
const segments = fields["Revenue by segment"].valueArray.map((row) =>
  Object.fromEntries(row.map((cell) => [cell.title, cell.value])),
);

Result

Illustrative: shape from the API reference. Field and column titles depend on the schema in your workspace. Rows are shortened here.

GET /v1/files/{fileId}/values?includeFullTableData=true

{
  "formValues": [
    {
      "id": "67ea5f20650d2fb5e33c3b17",
      "fileId": "9b2e4c71-0d3a-4f5e-8c21-6a7f1e0b9d42",
      "fileName": "annual-report-2025.pdf",
      "fileType": "application/pdf",
      "schemaName": "Annual Report",
      "fields": [
        { "title": "Reporting period start", "type": "string", "format": "date-time", "value": "2025-01-01" },
        { "title": "Reporting period end", "type": "string", "format": "date-time", "value": "2025-12-31" },
        { "title": "Total revenue", "type": "number", "value": 412850000 },
        { "title": "Auditor's opinion", "type": "string", "value": "Unqualified opinion: the financial statements give a true and fair view." },
        {
          "title": "Revenue by segment",
          "type": "list",
          "value": null,
          "valueArray": [
            [
              { "title": "Segment", "type": "string", "value": "Retail" },
              { "title": "Revenue current year", "type": "number", "value": 238400000 },
              { "title": "Revenue prior year", "type": "number", "value": 221900000 }
            ],
            [
              { "title": "Segment", "type": "string", "value": "Wholesale" },
              { "title": "Revenue current year", "type": "number", "value": 174450000 },
              { "title": "Revenue prior year", "type": "number", "value": 168300000 }
            ]
          ]
        },
        {
          "title": "Revenue by quarter chart",
          "type": "string",
          "value": "Bar chart of revenue by quarter for 2025 and 2024. Revenue rises each quarter in 2025, from about 95 million in Q1 to about 112 million in Q4."
        }
      ]
    }
  ],
  "count": 1,
  "currentPage": 1
}

Scalar fields carry their answer in value. Total revenue is a JSON number: grouped text such as 412,850,000 is read as 412850000. Reports often print figures in thousands or millions, so say in the field’s description which unit you want. See Extraction prompts.
Revenue by segment is a list field. Its value is null and its rows are in valueArray, each row an array of cells with their own title, type and value. A multi-level header (segment, then current year and prior year) comes back as flat, named columns. See Tables.
Revenue by quarter chart is a field that describes a visual element: here, what the chart shows. It is a reading of the chart, not the underlying data; when the report also prints the figures as a table, extract that table for exact numbers.
A number that is 0 comes back as null, in fields and in table cells. Treat null in a number field as zero or missing according to your own rules. See Data types.

What it shows

One upload handles a long, mixed file: tables, text, charts, photos and scanned pages are each read on their own path, so you don’t pre-sort pages.
Page furniture is skipped, so running headers and footers never turn into fields.
Long tables need includeFullTableData=true. Without it a table over 100 rows returns its first 100 and no error.
A chart comes back as a description. When you need exact figures, take them from a table.

Next steps

AI Schemas

Define the fields and tables fileScout fills.

Data types

Tables, valueArray and how values are typed.

Bank statement extraction

Long tables and a totals check.

Uploads

Every upload option, including enabledProducts.

Get started

Products

Build

Go live

Multi-page financial report

The job

Sample input

How fileScout processes it

Steps

Result

What it shows

Next steps

AI Schemas

Data types

Bank statement extraction

Uploads

​The job

​Sample input

​How fileScout processes it

​Steps

​Result

​What it shows

​Next steps

AI Schemas

Data types

Bank statement extraction

Uploads

The job

Sample input

How fileScout processes it

Steps

Result

What it shows

Next steps