FutureSmart Developer Docs
Open Document Intelligence

Extracted fields

Read the fields extracted from each document — one document at a time, or the whole collection as a table you can filter, sort and page.

When a document finishes processing, its fields are extracted according to the collection's field definitions — the ones you confirmed when you created it, editable under Settings → Extracted fields in the app. Every document also gets a summary, a document_type and its file_name.

The field definitions

GET /v1/{knowledge_id}/enrichment returns the collection's field definitions: each field's name, type and the instruction used to extract it. Read it to know which columns to expect. Changing definitions is done in the app.

One document

GET /v1/{knowledge_id}/documents/{object_id}/metadata

Python
import os
import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
COLLECTION_ID = os.environ["DOCUMENT_INTELLIGENCE_COLLECTION_ID"]
OBJECT_ID = os.environ["DOCUMENT_ID"]  # the object_id returned when the document was added

r = requests.get(
    f"{API_ROOT}/v1/{COLLECTION_ID}/documents/{OBJECT_ID}/metadata",
    headers={"x-api-key": os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
fields = r.json()["metadata"]
print(fields["vendor_name"], fields["total_amount"], fields["currency"], fields["due_date"])
for item in fields.get("line_items", []):
    print(f"  {item['quantity']} x {item['description']} @ {item['unit_price']}")

For an invoice collection the response looks like this — the keys are your collection's own fields:

JSON
{
  "object_id": "d1962692-6607-4db7-bdae-d656e3e0eba3",
  "metadata": {
    "summary": "This document is an invoice from Northwind Office Supply Co. to Cedar Lane Retail LLC …",
    "document_type": "invoice",
    "vendor_name": "Northwind Office Supply Co.",
    "customer_name": "Cedar Lane Retail LLC",
    "invoice_number": "INV-2026-0142",
    "total_amount": 1769.04,
    "currency": "USD",
    "issue_date": "2026-09-15",
    "due_date": "2026-10-15",
    "payment_terms": "net 30",
    "line_items": [
      { "description": "Ergonomic office chair", "quantity": 4.0, "unit_price": 189.0, "amount": 756.0 },
      { "description": "Standing desk frame", "quantity": 2.0, "unit_price": 312.5, "amount": 625.0 }
    ],
    "file_name": "invoice.pdf"
  }
}

A field the document does not contain is left out (or null in the table view below).

The whole collection as a table

POST /v2/{knowledge_id}/documents/metadata/all returns one row per document and one column per field — ready for a spreadsheet, a dataframe or a database table.

FieldMeaning
page, page_sizePage number (from 1) and rows per page (up to 100).
columnsOnly these top-level fields, for example ["vendor_name", "total_amount"]. Default: all.
filtersAn object keyed by field. A value matches exactly — {"document_type": "invoice"} — and an object of bounds matches a range — {"total_amount": {"gte": 1000}} (gt, gte, lt, lte). Conditions combine with AND.
sortA list of {"field", "order"}, for example [{"field": "due_date", "order": "asc"}]. Default: newest first.
Shell
curl -sS -X POST "https://futuresmart.ai/document-intelligence/api/v2/$DOCUMENT_INTELLIGENCE_COLLECTION_ID/documents/metadata/all" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"document_type": "invoice", "total_amount": {"gte": 1000}}, "sort": [{"field": "due_date", "order": "asc"}]}'
Python
import csv
import os

import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
COLLECTION_ID = os.environ["DOCUMENT_INTELLIGENCE_COLLECTION_ID"]
HEADERS = {"x-api-key": os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]}

rows, columns, page = [], None, 1
while True:
    r = requests.post(
        f"{API_ROOT}/v2/{COLLECTION_ID}/documents/metadata/all",
        headers=HEADERS,
        json={"page": page, "page_size": 100},
        timeout=60,
    )
    r.raise_for_status()
    table = r.json()
    columns = columns or [c["name"] for c in table["columns"]]
    rows += table["rows"]
    if page >= table["total_pages"]:
        break
    page += 1

with open("documents.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=columns, extrasaction="ignore")
    writer.writeheader()
    writer.writerows(rows)
print(f"Wrote {len(rows)} documents x {len(columns)} columns to documents.csv")

The response has columns (name, data type and how it maps to the field), rows, total_count, current_page, total_pages and extraction_context (per document, when its fields were extracted and which ones).

List fields such as line_items are spread over columns: the first entries get their own columns (line_items_0_amount, line_items_1_amount, …) and the rest are collected in line_items_remaining_* lists, so every row has the same shape. For the full nested list of one document, use the per-document call above.

POST /v1/{knowledge_id}/documents/metadata/all is the older cursor-paginated form of the same table (limit, page_offset, next_page_offset, has_more).

Fields inside the sections

GET /v1/{knowledge_id}/documents/{object_id}/chunks lists a document's indexed sections with their text and metadata; GET /v1/{knowledge_id}/chunks/{chunk_id}/metadata returns one section's fields. See the Sections reference.