Blocks - Retab Docs

Overview

Workflow blocks are the building blocks of document processing pipelines. Each block has specific inputs, outputs, and configuration options.

Block Categories

Blocks are organized into three categories:

Category	Purpose
Core	Workflow entry points and utilities
Tools	Document processing operations
Logic	Conditional flows and data transformations

Core Blocks

Document (Start)

Document

The entry point for your workflow. Upload documents here for processing.

Outputs: File Configuration: None (just upload your document in Run mode) Supported Formats:

PDF documents
Images (PNG, JPG, JPEG, GIF, WebP, TIFF, BMP)
Microsoft Word (.docx, .doc)
Microsoft Excel (.xlsx, .xls)
Microsoft PowerPoint (.pptx, .ppt)

Usage:

Drag multiple Document blocks for workflows that combine multiple inputs
Each Document block can receive one file per workflow run
Files are automatically converted to PDF when required by downstream blocks

JSON Input (Start)

JSON Input

Entry point for structured JSON data. Define a schema and pass JSON data when running the workflow.

Outputs: JSON Configuration:

Setting	Description
JSON Schema	Define the structure of expected input data

Schema Example:

{
  "type": "object",
  "properties": {
    "customer_id": { "type": "string" },
    "priority": { "type": "string", "enum": ["low", "medium", "high"] },
    "metadata": {
      "type": "object",
      "properties": {
        "source": { "type": "string" }
      }
    }
  },
  "required": ["customer_id"]
}

Usage:

Use JSON Input blocks to pass structured data into workflows without documents
Combine with Document blocks to enrich extractions with external data
Connect to Extract blocks as additional context for AI-powered extraction
Use with Function or If/Else blocks for data-driven workflow logic

SDK Example:

run = client.workflows.runs.create(
    workflow_id="wf_abc123",
    json_inputs={
        "json-block-id": {"customer_id": "cust_123", "priority": "high"}
    }
)

package main

import (
	"context"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func main() {
	ctx := context.Background()
	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	run, err := client.Workflows.Runs.Create(ctx, &retab.WorkflowRunsCreateParams{
		WorkflowID: "wf_abc123",
		JSONInputs: &map[string]any{
			"json-block-id": map[string]any{
				"customer_id": "cust_123",
				"priority":    "high",
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(run.ID)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

run = client.workflows.runs.create(
  workflow_id: 'wf_abc123',
  json_inputs: {
    'json-block-id' => { customer_id: 'cust_123', priority: 'high' },
  },
)

puts run.id

<?php
$run = $client->workflows()->runs()->create(
    workflowId: 'wf_abc123',
    jsonInputs: [
        'json-block-id' => ['customer_id' => 'cust_123', 'priority' => 'high'],
    ],
);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Retab;
using RetabClient = Retab.Retab;

var client = new RetabClient("YOUR_API_KEY");

// CreateAsync triggers a new workflow run; per-input documents/json maps are
// supplied through the request body emitted by the SDK.
var run = await client.Workflows.Runs.CreateAsync(
    new WorkflowRunsCreateOptions
    {
        WorkflowId = "wf_abc123",
        JsonInputs = new Dictionary<string, object>
        {
            ["json-block-id"] = new Dictionary<string, object>
            {
                ["customer_id"] = "cust_123",
                ["priority"] = "high",
            },
        },
    }
);

Console.WriteLine(run.Id);

const run = await client.workflows.runs.create(
  "wf_abc123",
  undefined,
  {
    "json-block-id": { customer_id: "cust_123", priority: "high" },
  },
);

console.log(run.id);

use retab::{models::CreateWorkflowRunRequest, resources::workflow_runs, Retab};
use std::collections::HashMap;

let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let mut request = CreateWorkflowRunRequest::new("wf_abc123");
request.json_inputs = Some(HashMap::from([(
    "json-block-id".to_string(),
    serde_json::json!({ "customer_id": "cust_123", "priority": "high" }),
)]));
let run = client
    .workflows().runs()
    .create(workflow_runs::CreateParams::new(request.into()))
    .await?;

println!("{}", run.id);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().runs().create("wf_abc123", null, null, null, null);
    System.out.println(result);
  }
}

Note

Add comments and documentation to your workflow.

Inputs: None
Outputs: None Notes don’t affect workflow execution—they’re purely for documentation. Use them to:

Explain complex logic
Document configuration choices
Leave instructions for teammates

Tool Blocks

Extract

Extract structured data from documents using a JSON schema.

Inputs: File, plus optional additional inputs (JSON, File) Outputs: JSON (extracted data) Configuration:

Setting	Description	Default
Schema	JSON Schema defining fields to extract	`{}`
Model	AI model for extraction	`retab-small`
Consensus	Number of parallel extractions (1-10)	`1`
Additional Inputs	Named inputs for context (JSON or files)	`[]`

Schema Example:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "total_amount": { "type": "number" },
    "vendor": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": { "type": "string" }
      }
    }
  }
}

Consensus Mode:
When n_consensus > 1, the block runs multiple extractions in parallel and returns the consensus data on output-json-0. Field likelihoods are retained as consensus metadata for review and inspection, not as workflow output handles. Additional Inputs: You can add named input handles to provide extra context during extraction:

JSON inputs: Structured data from other blocks
File inputs: Additional reference documents

Parse

Parse documents into machine-usable JSON with a Pages array.

Inputs: File
Outputs: JSON ({"Pages":[...]}) Configuration:

Setting	Description	Default
Model	AI model for parsing	`retab-small`

Use Cases:

Generate page-by-page JSON content for indexing/RAG pipelines
Add parsed page context to Extract as additional JSON input
Convert scanned PDFs to machine-usable page content

Split

Split multi-page documents into separate PDFs by subdocument.

Inputs: File (PDF)
Outputs: Multiple File outputs (one per subdocument) Configuration:

Setting	Description
Subdocuments	List of document subdocuments with names and descriptions
Model	AI model for classification

Subdocument Example:

{
  "subdocuments": [
    {
      "name": "Invoice",
      "description": "Pages containing invoice details, line items, and totals"
    },
    {
      "name": "Contract",
      "description": "Legal agreement pages with terms and signatures"
    },
    {
      "name": "Supporting Documents",
      "description": "Receipts, certificates, and other attachments"
    }
  ]
}

Each category creates a separate output handle. Connect downstream blocks to process each category differently.

Non-PDF documents are automatically converted to PDF before splitting.

Classifier

Classify documents into one of the predefined categories.

Inputs: File
Outputs: Multiple File outputs (one per category, only the matched category receives the document) Configuration:

Setting	Description
Categories	List of document categories with names and descriptions
Model	AI model for classification

Difference from Split:

Feature	Split	Classifier
Input	Multi-page document	Single document
Output	Multiple PDFs (pages grouped by category)	Same document routed to one category
Use Case	Separating bundled documents	Routing different document types

Example:

{
  "categories": [
    {
      "name": "Invoice",
      "description": "Documents containing billing information and payment requests"
    },
    {
      "name": "Receipt",
      "description": "Proof of payment or purchase confirmation"
    },
    {
      "name": "Contract",
      "description": "Legal agreements and binding documents"
    }
  ]
}

The AI analyzes the document and routes it to exactly one category. Downstream blocks connected to other categories are skipped.

Edit

Fill PDF forms using AI with JSON instructions or pre-defined templates.

Inputs:

File (document to edit) — only when “Use Template” is off
JSON (instructions/data)

Outputs: File (filled document) Configuration:

Setting	Description
Model	AI model to use for filling
Use Template	Toggle to use a pre-defined template instead of an input document
Template	Template to use (shown when “Use Template” is on)

Two Operating Modes:

Document Mode (default): Edit an input document using AI
- Connect a document from another block (e.g., Start, Split)
- Provide instructions via the JSON input
- The AI fills the form fields based on your instructions
Template Mode: Fill a pre-defined template
- Enable “Use Template” toggle
- Select a template from your template library
- No document input required — the template provides the form structure
- Provide data/instructions via the JSON input

Example Instructions (JSON):

{
  "name": "Acme Corp",
  "address": "12 Main St",
  "notes": "Leave signature fields blank"
}

The JSON input provides instructions/data for filling. Connect this to an Extract block’s JSON output for end-to-end automation.

Logic Blocks

Review Gates

Review Gate

Pause a gated block for review and approval.

Review is not a separate workflow block. Configure review on a block that supports review, such as extract, split, classifier, or for_each with map_method: "split_by_key". When the gate predicate fires, that same block enters awaiting_review and a review is created with an opaque review id. Configuration: config.review How It Works:

Add review to the block config.
Choose a predicate such as always, any_required_field_null, or field_confidence_lt.
When the predicate fires, the block pauses at awaiting_review.
A reviewer sees the block output alongside the source document.
The reviewer can approve the inspected version_id, append a corrected version with parent_version_id, or reject through Reviews.
After approval, the selected versions[decision.version_id].snapshot continues through the workflow.

Use Cases:

Validate critical extractions before sending to downstream systems
Quality control for high-value documents
Compliance requirements that mandate human oversight

Example extract gate:

{
  "model": "retab-small",
  "inputs": [{ "name": "document", "type": "file", "is_primary": true }],
  "json_schema": {
    "type": "object",
    "required": ["invoice_number", "total"],
    "properties": {
      "invoice_number": { "type": "string" },
      "total": { "type": "number" }
    }
  },
  "review": {
    "predicate": {
      "kind": "any_required_field_null"
    }
  }
}

Common extract predicates include always, validation_failed, confidence_lt, any_required_field_null, and field_confidence_lt. For split and split-by-key for_each gates, use split-style predicates such as split_count_neq, any_split_pages_lt, and boundary_confidence_lt.

The review object is actor-neutral: a model output, an agent-created correction, and a human-created correction all use the same versions and decision.version_id shape. There is no separate agent-review configuration on config.review; automated reviewers should create correction versions through client.workflows.reviews.versions.create(...) and then approve or reject through client.workflows.reviews.*.

Function

Execute function code in a sandboxed environment for transformations and validations. The language field currently supports Python.

Inputs: JSON Outputs: JSON (with computed/transformed fields) Configuration:

Setting	Description
language	Execution language. Currently only `Python` is supported
output_schema	JSON schema defining the output structure
code	Python code with a `transform(input_data: Input) -> Output` function
timeout_seconds	Sandbox execution timeout (1—300, default 60)

Example:

from models import Input, Output

def transform(input_data: Input) -> Output:
    subtotal = sum(item.amount for item in input_data.line_items)
    tax = subtotal * 0.1
    total = subtotal + tax
    return Output(subtotal=subtotal, tax=tax, total=total)

Available packages: pydantic, pandas, numpy, scipy, duckdb, rapidfuzz, beautifulsoup4, lxml, python-dateutil.

Outbound network access is disabled. Use the api_call block for HTTP requests.

See Functions Documentation for the complete reference.

Use Cases:

Restructure flat data into nested objects for downstream systems
Select only the fields you need from a large extraction
Rename fields to match your API or database schema
Prepare data for downstream APIs or databases that expect a specific format

Unmapped fields are excluded from the output. If an input path doesn’t exist, the mapping is skipped without error.

If / Else

Route data to different branches based on conditions.

Inputs: JSON
Outputs: Multiple JSON outputs (one per branch: If, Else If, Else) Configuration:

Setting	Description
Conditions	List of conditions to evaluate in order
Has Else	Whether to include a default else branch (default: true)

Condition Structure: Each condition can have multiple sub-conditions combined with AND/OR:

{
  "conditions": [
    {
      "branch_name": "if",
      "sub_conditions": [
        {
          "path": "data.total_amount",
          "operator": "is_greater_than",
          "value": 1000
        },
        {
          "path": "data.vendor.country",
          "operator": "is_equal_to",
          "value": "US"
        }
      ],
      "logical_operator": "and"
    }
  ]
}

Available Operators:

Type	Operators
Existence	`exists`, `does_not_exist`, `is_empty`, `is_not_empty`
Comparison	`is_equal_to`, `is_not_equal_to`
String	`contains`, `starts_with`, `ends_with`, `matches_regex`
Number	`is_greater_than`, `is_less_than`, `is_greater_than_or_equal_to`, `is_less_than_or_equal_to`
Boolean	`is_true`, `is_false`
Array	`length_equal_to`, `length_greater_than`, `length_less_than`
Date	`is_after`, `is_before`, `is_after_or_equal_to`, `is_before_or_equal_to`

How It Works:

Conditions are evaluated in order (If, Else If 1, Else If 2, …)
The first matching condition determines the output branch
Data is routed to exactly one branch
If no conditions match and has_else is true, data goes to the Else branch
Downstream blocks on non-matched branches are skipped

Example Use Cases:

Route high-value invoices for additional approval
Process documents differently based on vendor country
Flag incomplete extractions for review

API Call

Make HTTP requests to external APIs and use the response in your workflow.

Inputs: JSON (optional request body or parameters) Outputs: JSON (API response) Configuration:

Setting	Description	Default
URL	The API endpoint URL	Required
Method	HTTP method (GET, POST, PUT, PATCH, DELETE)	`POST`
Headers	Custom HTTP headers (e.g., authentication)	`{}`
Request Schema	JSON schema used to select request-body fields from the input JSON	Optional
Field Mappings	Optional target-field to source-path mapping before schema filtering	`{}`
Output Schema	JSON schema describing the response for downstream workflow blocks	Optional

Example Configuration:

{
  "url": "https://api.example.com/validate",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json"
  },
  "field_mappings": {
    "invoice_number": "data.invoice_number",
    "amount": "data.total_amount"
  },
  "request_schema": {
    "type": "object",
    "properties": {
      "invoice_number": {"type": "string"},
      "amount": {"type": "number"}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "valid": {"type": "boolean"}
    }
  }
}

Use Cases:

Validate extracted data against external systems
Enrich documents with data from your CRM or ERP
Trigger actions in third-party services based on extraction results
Look up additional information using extracted identifiers

For POST, PUT, and PATCH requests, the block sends the full input JSON as the request body by default. Add field_mappings to rename or derive top-level request fields from dot paths in the input JSON, then use request_schema to keep only the fields the external API expects.

API Call blocks execute synchronously. For long-running operations, prefer async endpoints or job-based integrations on the external system.

Merge JSON

Combine multiple JSON objects into a single structured object.

Inputs: Multiple JSON inputs (configurable)
Outputs: JSON (merged object) Configuration:

Setting	Description
Inputs	Named input slots for JSON objects to merge

Example Configuration:

{
  "inputs": [
    { "name": "invoice_data" },
    { "name": "vendor_data" },
    { "name": "line_items" }
  ]
}

Output Structure: The merged output wraps each input under its named key:

{
  "invoice_data": { ... extracted invoice fields ... },
  "vendor_data": { ... extracted vendor fields ... },
  "line_items": { ... extracted line items ... }
}

This is useful for:

Combining extractions from multiple documents
Aggregating data from parallel processing branches
Creating comprehensive outputs from Split or Classifier workflows

While Loop

Repeat contained blocks until a termination condition is met.

Inputs: JSON or File Outputs: JSON or File (final iteration result) Configuration:

Setting	Description	Default
Max Iterations	Maximum number of loop iterations	`10`
Termination Conditions	Conditions that stop the loop when matched	`[]`
Loop Context Template	Text template with loop variables for contained blocks	`""`

How It Works:

Data enters the loop through the left input handle
Contained blocks inside the loop process the data
After each iteration, termination conditions are evaluated
If a condition matches (or max iterations reached), the loop exits
Final output is passed through the right output handle

Termination Conditions: Configure conditions using the same operators as If/Else:

Type	Operators
Comparison	`is_equal_to`, `is_not_equal_to`, `is_greater_than`, `is_less_than`
Existence	`exists`, `does_not_exist`, `is_empty`, `is_not_empty`
Boolean	`is_true`, `is_false`
Array	`length_equal_to`, `length_greater_than`, `length_less_than`

Example Configuration:

{
  "max_iterations": 5,
  "termination_conditions": [
    {
      "path": "data.status",
      "operator": "is_equal_to",
      "value": "complete"
    }
  ]
}

Loop Context Variables: The loop context template can include these variables:

{{iteration_number}} - Current iteration (e.g., “1 of 10”)
{{termination_condition_breakdown}} - Detailed evaluation of why the loop continued
{{data}} - JSON data from the previous iteration

Use Cases:

Iteratively refine extractions until quality thresholds are met
Process documents until a specific field value is detected
Implement retry logic with conditional exit

The loop always runs at least once. Termination conditions are evaluated after each iteration completes.

For Each

Process items in parallel and combine results.

Inputs: JSON (array) or File (PDF) Outputs: JSON (combined results) Configuration:

Setting	Description	Default
Map Method	How to split input into items	`split_by_page`
Allow Overlap	For `split_by_key`, whether keyed chunks may share pages	`false`
Max Iterations	Maximum items to process	`100`
Reduce Strategy	How to combine iteration outputs	`concat_array`

Map Methods:

Method	Description	Input Type
`iterate_array`	Process each item in a JSON array	JSON
`split_by_page`	Split PDF into N-page chunks	File
`split_by_key`	Split PDF by semantic boundaries (AI-detected)	File

Reduce Strategies:

Strategy	Description	Output Type
`concat_array`	Combine all outputs into an array	JSON
`first`	Return only the first iteration’s output	JSON
`last`	Return only the last iteration’s output	JSON
`none`	No output (side effects only)	None

Example: Iterate Array Process each line item in an invoice separately:

{
  "map_method": "iterate_array",
  "map_source_path": "data.line_items",
  "reduce_strategy": "concat_array",
  "reduce_concat_data_key": "processed_items"
}

Example: Split by Page Process a multi-page document one page at a time:

{
  "map_method": "split_by_page",
  "split_page_range": 1,
  "reduce_strategy": "concat_array"
}

Example: Split by Key Split a document containing multiple invoices by invoice number:

{
  "map_method": "split_by_key",
  "key": "invoice_number",
  "instructions": "Invoice number found at the top of each invoice",
  "allow_overlap": true,
  "reduce_strategy": "concat_array",
  "reduce_concat_item_key": "invoice_id"
}

Set "allow_overlap": false only when keyed partitions must be exclusive. The default true allows multiple keyed partitions to include the same page. Add map-phase review to inspect the proposed split boundaries before the for-each body runs:

{
  "map_method": "split_by_key",
  "key": "invoice_number",
  "instructions": "Invoice number found at the top of each invoice",
  "review": {
    "predicate": {
      "kind": "boundary_confidence_lt",
      "threshold": 0.8
    }
  }
}

Iteration Context: Inside the loop, contained blocks can access:

{{key}} - The partition key for the current item (page range or semantic key)
{{input_json}} - The full input JSON (for iterate_array method)

Use Cases:

Extract data from each page of a multi-page document independently
Process bundled documents that contain multiple invoices/receipts
Apply different logic to each item in an array
Batch process documents with parallel execution

For Each processes items sequentially. The reduce phase runs after all iterations complete. Use split_by_key when documents have multiple logical sections that need AI to identify boundaries.

Block I/O Types

Understanding input/output types helps you connect blocks correctly:

Type	Color	Description
File	Blue (📎)	Documents, PDFs, images
JSON	Purple (`{ }`)	Structured data objects

Tips for Building Workflows

Start with the output in mind

Identify what data you need at the end, then work backwards to determine which blocks you need.

Add Function blocks for calculations

Instead of computing values after reading workflow results elsewhere, use Function blocks to add totals, percentages, and derived fields directly in the workflow.

Use Classifier for routing

When handling different document types, use Classifier to route each document to the appropriate extraction schema before processing.

Split before specialized processing

When handling mixed document bundles (e.g., invoice + contract in one PDF), use Split first, then apply specific Extract schemas to each subdocument.

Combine results with Merge JSON

When processing multiple documents or branches, use Merge JSON to combine all extracted data into a single structured output.

Use If/Else for conditional logic

Route data based on extracted values—for example, send high-value invoices to a different API endpoint or flag certain conditions for review.

Use For Each for multi-document PDFs

When a single PDF contains multiple logical documents (like several invoices), use For Each with split_by_key to process each one independently with its own extraction.

Use While Loop for iterative refinement

When you need to retry or refine processing until a quality threshold is met, use While Loop with termination conditions that check for the desired outcome.

Test edge cases

Run your workflow with documents that have missing fields, poor scan quality, or unusual formats to ensure robust handling.

​Overview

​Block Categories

​Core Blocks

​Document (Start)

Document

​JSON Input (Start)

JSON Input

​Note

Note

​Tool Blocks

​Extract

Extract

​Parse

Parse

​Split

Split

​Classifier

Classifier

​Edit

Edit

​Logic Blocks

​Review Gates

Review Gate

​Function

Function

​If / Else

If / Else

​API Call

API Call

​Merge JSON

Merge JSON

​While Loop

While Loop

​For Each

For Each

​Block I/O Types

​Tips for Building Workflows

Overview

Block Categories

Core Blocks

Document (Start)

JSON Input (Start)

Note

Tool Blocks

Extract

Parse

Split

Classifier

Edit

Logic Blocks

Review Gates

Function

If / Else

API Call

Merge JSON

While Loop

For Each

Block I/O Types

Tips for Building Workflows