> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Conditional Extraction Step

> How to use the Conditional Extraction step to dynamically route documents to different extractors.

The Conditional Extraction step allows you to dynamically route documents to different extractors based on variable values available within a workflow execution, including previous step outputs, external data fetches, and run metadata that you provided. This is particularly useful when you need to apply different extraction processors based on known or extracted document characteristics.

## Use Cases

Common use cases for conditional extraction include:

1. **Document Content-Based Routing**: Route documents to specialized extractors based on previous steps results
2. **Metadata-Driven Routing**: Use metadata you send in your API request to determine which extractor to use

## Via the API

In a workflow definition the step is `type: "CONDITIONAL_EXTRACT"`. `rules` are evaluated in order; each pairs a [formula](/workflows/formulas) with a saved extractor reference (inline configs are not supported here). The last rule must use `formula: "TRUE"` as the catch-all, otherwise a run that matches no rule fails.

```json
{
  "name": "route_extractor",
  "type": "CONDITIONAL_EXTRACT",
  "config": {
    "rules": [
      {
        "name": "cigna_provider",
        "formula": "metadata.provider_name = \"cigna\"",
        "extractor": { "id": "ex_cigna", "version": "1.0" }
      },
      {
        "name": "fallback",
        "formula": "TRUE",
        "extractor": { "id": "ex_generic", "version": "1.0" }
      }
    ]
  },
  "next": [{ "step": "validate" }]
}
```

Formulas can reference run `metadata` (as above) or a previous step's output by step name, for example `classification1 = "invoice"` or `extraction1.provider_name = "cigna"`. See [Conditional Extract in the step reference](/workflows/configuring-workflows#conditional-extract) for the field list and how to deploy the definition.

## Via Extend Studio

To configure the Conditional Extraction step, add it to your workflow and click the "Configure" button.

![Workflow builder step drawer with the Conditional Extraction step](/_fern-img/6c997e4b11cd8b16b74db68a79f1e3766c604504f300a3cc6de953cb4320c6f2.webp)
![Empty Conditional Extraction configuration panel](/_fern-img/59a5759627a61329f2f0031b1e9b919fc4c9b3a36ee2817bf4a1eadc581bd853.webp)

The configuration has two main sections:

### 1. Variable Selection

First, select the variable that will determine which extractor to use. Hook up the step to previous steps to have these variables available. You can choose from:

* Variables from previous steps in your workflow
  * Extraction outputs
  * External Data Validation step outputs
  * Classification outputs
* Metadata fields from your API request

The selected variable's value will be used to match against your defined routes.

The variable input autocompletes with the variables from previous steps. However, to add a metadata field or an external data validation field, just type the variable name in the input field and select the variable from the dropdown.

### 2. Extractor Routes

Next, configure the routing logic by defining conditions and their corresponding extractors:

1. **Add Routes**: Click "Add Route" to create new conditional paths
2. **Define Values**: Enter the variable values that should trigger each route
3. **Select Extractors**: Choose which extractor and version should process documents for each condition
4. **Default Route**: A default route is always required to handle cases where no conditions match

## Example Extraction-Driven Routing Configuration

Here's an example of how to configure conditional extraction based on a previously extracted field:

Let's say you have a lot of insurance documents and you want to route them to different extractors based on the `provider_name` field.

1. Set the variable to the `provider_name` field which will be available after you connect the extraction1 step:

```
extraction1.output.provider_name.value
```

You can select the `extraction1` variable from the dropdown.

2. Configure routes:

* If value equals "cigna" → Use Cigna Extractor v1.0
* If value equals "aetna" → Use Aetna Extractor v1.0
* Default → Use Generic Insurance Extractor v1.0

![Completed configuration routing on an extracted provider\_name value to three extractors](/_fern-img/44e97e0366fcf01b2974f5c8b6725d9fa87864ac91efd07bdd8ba7f9cd050fe7.webp)

3. Click "Save"

## Example Metadata-Driven Routing Configuration

Here's an example of how to configure conditional extraction based on a metadata field:

1. Set the variable to the metadata field `provider_name` which you would send in your API request:

```
metadata.provider_name
```

2. Configure routes:

* If value equals "cigna" → Use Cigna Extractor v1.0
* If value equals "aetna" → Use Aetna Extractor v1.0
* Default → Use Generic Insurance Extractor v1.0

![Completed configuration routing on a run metadata value to three extractors](/_fern-img/3e28ec46de4b9a00d7d9d77ca7b3c40b63109fd372595c5d5eefc4e1efbe1e4b.webp)

3. Click "Save"

> Ship your document processing with Extend. Get started with our APIs, SDKs, and guides.