HIL Interface

The HIL (Human-in-the-Loop) Interface is a shareable document preview tool at preview.deepread.tech that displays original images side-by-side with extracted text and highlights pages flagged for human review.

IMPORTANT: The HIL preview is opt-in: send preview=true on any plan to store page images and get a preview URL. The link is readable by anyone who has it, so a job without preview=true leaves none behind. Field locations (location.bounding_box) come back in the response when you send include_markers=true. To highlight a value's source in the preview, send include_markers=true together with preview=true.

Key Capabilities

• Side-by-side view: Original document images alongside extracted text
• Review indicators: Visual flags for pages needing verification
• Page navigation: Browse multi-page documents easily
• Public access: Shareable links, no authentication required
• Mobile-friendly: Responsive interface for all devices
• Assigned reviews: Name a reviewer on the job and the same screen becomes their review screen

Assigning a reviewer

Send reviewer_email with the job (one email, or a team separated by commas) and DeepRead runs the review:

1. The reviewer is emailed a link when the document is ready. It signs them in with a code sent to that address, so no account or password is needed.
2. On the review screen, flagged values are marked. The reviewer corrects what is wrong and presses Complete. Every correction records who made it.
3. Your webhook receives review.completed with the corrected values, and review.updated for any correction made afterwards.

Each reviewer's /reviews page lists every document waiting for them, most urgent first. Add review_due_hours for a deadline and you get review.overdue when it passes. See Human review in the API reference for the parameters, the review fields on the job and the owner endpoint that reassigns or cancels a review.

Retrieving the HIL UI URL

When preview=true, page images are saved to cloud storage and the completed job response includes artifacts.preview_url plus per-page review flags:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "schema_version": "dp02",
  "pages": [
    {
      "page_number": 1,
      "content": { "format": "markdown", "text": "Page 1 text..." },
      "needs_review": false,
      "review_reason": null
    }
  ],
  "review": {
    "review_rate": 0.05
  },
  "artifacts": {
    "preview_url": "https://preview.deepread.tech/abc123xyz"
  }
}

Key response fields

• artifacts.preview_url: Shareable link to the HIL Interface (present when you send preview=true, on every plan; field locations come back with include_markers=true). Images are stored in public cloud storage for fast, CDN-backed access.
• pages[].needs_review: Boolean flag indicating if a page needs verification
• pages[].review_reason: Explanation if the page was flagged

What the Interface Shows

The HIL Interface displays:

1. Document metadata: File name, page count, status, review percentage
2. Side-by-side view: Original image on the left. On the right, two tabs are available:
   • Per-Page tab: Extracted text per page, viewable in Structured (formatted) or Raw JSON format
   • Schema tab: Structured JSON with extracted fields (only shown if a schema was provided)
3. Review badges: Visual indicators for flagged pages with reasons

Live Example

See the HIL Interface in action: https://preview.deepread.tech/RPiRmc6

Security Considerations

• Token-based URLs: Preview links use secure random tokens and are not publicly discoverable
• Retention: By default, uploaded documents, page images and results are kept so the preview keeps working and you can come back to them. Enterprise plans set their own window per job with the retention_days option (1–365 days): at the deadline the document, page images and results are deleted and the preview link answers 410 Gone. Enterprise agreements can also set a contractual retention window
• HTTPS only: All preview URLs use encrypted connections

For sensitive documents, limit preview URL sharing to authorized personnel or use internal review systems. On Enterprise plans, use incognito=true to keep the submitted document out of storage entirely (no preview link is created), and retention_days to have everything deleted on a schedule — see Incognito Processing and Retention in the OCR API reference. For contractual retention terms beyond that, contact us.

Related Concepts

• Human Review Flags - Understanding needs_review flags
• Jobs & Webhooks - Receiving job completion notifications
• Handling Results - Processing webhook payloads and results