Reading Results

A completed processing run can produce structured schema results, a generated document description, searchable content, and one or more result files.

Review results in Shipwell

1. Open a completed document.
2. Open the latest run.
3. Review the document summary.
4. Open Schemas to review structured values.
5. Select a value to locate its source when source regions are available.
6. If the document was split, move between its result slices.

Retrieve results for a run

Use the run identifier with GET /document-store/documents/{id}/results?run_id={run_id} to retrieve every result created by that run.

The response is paginated. Each result contains:

• id — result identifier
• run_id — processing run that created the result
• document_id — source document
• schemas — structured extraction results
• split_metadata — information about the result slice when splitting is enabled
• output_file_ref — reference for a generated result file, when one exists
• page_count
• created_at and updated_at

Use the result id when downloading or inspecting a specific split result.

Read schema results

Each item in schemas corresponds to a schema in the processing configuration.

{
  "name": "purchase_order_number",
  "value": "PO-10482",
  "json_schema": {
    "type": ["string", "null"]
  },
  "prompt": "Extract the purchase order number. Return null when absent.",
  "source_regions": [
    {
      "left": 0.12,
      "top": 0.18,
      "width": 0.21,
      "height": 0.03
    }
  ],
  "scope": "document",
  "result_cardinality": "single"
}

For application logic:

1. Select results by name .
2. Validate value against the schema contract your integration expects.
3. Handle null or missing results explicitly.
4. Use source_regions for review experiences, not as the extracted business value.
5. Ignore response fields your integration does not use.

Multiple results

When result_cardinality is multiple, the schemas array can contain several entries with the same name. Do not assume schema names are unique within a result.

When the schema's json_schema defines an array, one schema-result entry can itself contain an array value. That is different from result_cardinality: "multiple".

Split documents

When split is enabled and multiple logical documents are detected:

• One uploaded document can have multiple result rows.
• Each result row represents a detected document slice.
• split_metadata identifies the source pages for the slice.
• A result file may be available for each slice.
• Page numbers continue to refer to the uploaded parent document.

Use the complete result list for the run. Do not rely on GET /documents/{id}/results/latest when you need every slice; that endpoint returns only the newest single result row.

Generated descriptions

When auto-description is enabled, a successful run updates the document's description. Retrieve the document to read the current description:

Use GET /document-store/documents/{id} and read description.

A later successful run with auto-description enabled can replace that description. Preserve a prior value in your own system if your workflow requires historical comparison.

Inspect supporting content

Use the read-only investigation endpoints when your application needs:

• A document outline
• Extracted text for one page
• Key-value fields
• Detected signatures

See Inspecting Content and Signatures.

Result handling recommendations

• Key downstream work by document_id and run_id .
• Treat each run as immutable history.
• Expect schema values to be absent when the source document does not contain them.
• Validate values before applying automated business actions.
• Keep a human review step for high-impact decisions.
• Use webhook events as a signal to retrieve the current resource; do not treat an event as the complete result.