Accessing OCR & Field Data

This guide covers how to pull a transaction's extracted fields and OCR layout out of DocAI Fabric over the API, with everything you need to build your own review interface (a human-in-the-loop client): field values, confidence, reasoning, confirmation state, and bounding boxes that line up with the page.

All calls use API-key authentication (see Authentication) and require the transaction.download_results permission.

Recommended approach: export profile

The primary, supported way to get results is to configure a JSON export profile on your project's workflow, then retrieve the output over the API. The workflow decides exactly what each transaction produces, so your client stays simple and every transaction is consistent.

Set up a JSON profile on the Export activity. For a review client, keep the defaults (field values, confidence, reasoning, confirmation state, and per-field bounding boxes) and enable Include Page OCR Data if you also want the full word-level OCR layout. See Export to JSON for the complete structure.

If your client also needs the page images (to render the page and overlay the boxes on it), add a JPG profile to the same Export activity. It produces one JPEG per page, exported exactly as OCR saw it, so the JSON coordinates land on it with no conversion. Retrieving it uses the same manifest and download calls shown below. This is the supported way to get page images; see Working with coordinates.

Retrieve the export

List the export manifest for a finished transaction:

curl -H "X-API-Key: $API_KEY" \
  https://app.docaifabric.com/transactions/{transaction_id}/exports

The manifest lists each profile and the files it produced:

{
  "transaction_id": "…",
  "profiles": {
    "json_default": {
      "status": "success",
      "files": [
        { "filename": "invoice.json", "path": "exports/invoice.json", "size_bytes": 4210 }
      ]
    }
  }
}

Download a file using its filename from the manifest:

curl -H "X-API-Key: $API_KEY" \
  https://app.docaifabric.com/transactions/{transaction_id}/exports/download/invoice.json

The JSON contains the fields and pages described in Export to JSON. Each field carries:

"invoice_number": {
  "value": "INV-1001",
  "confidence": 0.99,
  "reasoning": "Found under INVOICE NO. label",
  "is_confirmed": true,
  "bounding_boxes": [ { "coordinates": [10, 10, 100, 30], "page_index": 1 } ]
}

That is everything a review UI needs: the value to display, the confidence to flag low-certainty fields, the reasoning to explain the model's choice, is_confirmed to track review state, and the box to highlight on the page.

Page dimensions and metadata

Every page in the export carries its size, orientation, and coordinate frame under image_transform, alongside a reference back to the source file it came from. These dimensions are in the same coordinate space as every OCR and field bounding box (words, lines, tables and fields), so you can map extracted content onto the page precisely.

"pages": [
  {
    "page_number": 1,
    "transaction_page_number": 1,
    "source_filename": "invoice.pdf",
    "source_file_page_number": 1,
    "image_transform": {
      "rasterized_width": 2480,
      "rasterized_height": 3508,
      "source_width": 595.32,
      "source_height": 841.92,
      "source_unit": "point",
      "render_scale": 4.166,
      "effective_dpi": 300.0,
      "coordinate_system": "top-left-origin",
      "rotation": 0
    }
  }
]

Field	Meaning
`page_number`	1-based page position within the document. Matches each box's `page_index`.
`source_filename` / `source_file_page_number`	The original file and 1-based page within it that this page came from, for mapping back onto the source document.
`rasterized_width` / `rasterized_height`	Pixel size of the OCR'd image. This is the coordinate space of every bounding box.
`source_width` / `source_height` / `source_unit`	Original page size and its unit (`point` for PDF, `pixel` for image sources).
`render_scale` / `effective_dpi`	Rasterized pixels per source unit, and the true DPI (`render_scale x 72`, or `null` for image sources). Divide a coordinate by `render_scale` to reach the source page.
`coordinate_system`	Always `top-left-origin`.
`rotation`	Display rotation in degrees clockwise, applied after OCR. Exported coordinates are pre-rotation.

See Export to JSON for the full page structure.

Working with coordinates

Every bounding box, both field boxes (coordinates) and OCR word boxes (bounding_box), is in the rasterized page-image pixel space, top-left origin. There are two ways to render them, depending on which page image you draw on.

Option A: overlay on the exported page image (simplest)

Add a JPG profile to your Export activity (see JPG output). It exports one JPEG per page, and the JSON coordinates match it exactly, with no conversion.

Leave the JPG profile's Resolution at Original for this to hold. Reducing the resolution rescales the page images, so the JSON coordinates no longer line up. The Compression option is safe: it does not change pixel dimensions, so coordinates still match.

Retrieve the images the same way as the JSON file. In the export manifest each page image appears as a separate file named with a page suffix, for example invoice_page_1.jpg. The number is the transaction page number, which matches each bounding box's page_index in the JSON. Download the one you need:

curl -H "X-API-Key: $API_KEY" \
  https://app.docaifabric.com/transactions/{transaction_id}/exports/download/invoice_page_1.jpg \
  --output page_1.jpg

Then draw each box at its [x1, y1, x2, y2] pixel coordinates on the image whose page number matches the box's page_index. The exported image is un-rotated, matching the coordinate space of the boxes.

Use this when you are happy to show the platform's page image in your client.

Option B: map back onto the original page (for example the source PDF)

If your client renders the customer's original PDF (or original image) instead, convert each coordinate using the page's image_transform frame from the export:

original_coordinate = rasterized_coordinate / render_scale

For example, with render_scale of 4.166, a field box [10, 10, 100, 30] maps to roughly [2.4, 2.4, 24.0, 7.2] in source units (points, for a PDF). The image_transform block also gives you source_width / source_height (the original page size) and rotation, so you can position and orient the overlay precisely. The scaling is uniform on both axes and involves no cropping, so a single divide is exact.

Use this when you keep the original files and want pixel-accurate overlays on them.

Live per-page endpoints (not recommended)

The platform also exposes the page image and OCR layout live, per page:

GET /transactions/{transaction_id}/pages/{page_index}/image
GET /transactions/{transaction_id}/pages/{page_index}/ocr

Not a supported integration surface

These endpoints back the platform's own viewer and are considered internal. Their paths, parameters, and response shapes may change without notice and carry no backward-compatibility guarantee. Do not build an integration on them.

Use the export profiles above instead: a JSON profile for the data and coordinates, and a JPG profile for the page images. Export output is the supported, stable contract, and a workflow guarantees every transaction produces the same files.

Recommended approach: export profile​

Retrieve the export​

Page dimensions and metadata​

Working with coordinates​

Option A: overlay on the exported page image (simplest)​

Option B: map back onto the original page (for example the source PDF)​

Live per-page endpoints (not recommended)​