> Source: https://builder-docs.ema.ai/agent-reference/core/json-extractor
> Title: JSON Extractor Agent

# JSON Extractor Agent

The JSON Extractor agent extracts specific values from a nested JSON object (or any agent output) and flattens them into named variables for use by downstream agents. It is a deterministic agent -- no LLM is involved.

## Use Cases

-   An upstream agent returns complex nested JSON and you need specific fields for downstream processing.
-   You need to flatten a deeply nested API response into a simple, flat structure.
-   You want to expose extracted fields as template variables in a [Fixed Response](/legacy-docs/agent-reference/core/fixed-response).
-   You want to supply structured data to a [Categorizer](/legacy-docs/agent-reference/core/categorizer)'s qualification criteria.

## Inputs

Input

Type

Required

Description

`input_json`

Any

Yes

The nested data to extract from. Shown in the builder as **JSON**. Accepts output from any upstream agent -- JSON objects, lists, Text with Sources, extraction results, and more.

## Outputs

Output

Type

Description

`output_json`

Struct

A flat key-value object containing the extracted fields. Shown in the builder as **Variables**. Each extracted field is available as a template variable (e.g., `{{variable_name}}`) in downstream agents.

## Configurations

Parameter

Description

Default

**Add sample input**

A sample JSON value used to validate the input shape and populate the JSON Path picker with the list of available fields. You can upload a `.json` file or paste JSON directly.

Required

**JSON Extractor Configuration**

The list of mapping rules. Each rule defines one output variable. See _Configuring Mapping Rules_ below.

Required

### Configuring Mapping Rules

Click **Create JSON Mapping** to add a rule. Each rule has five fields:

-   **Variable name** -- the output key. Must start with a letter or underscore and contain only letters, numbers, and underscores (camelCase recommended). Cannot be changed once saved.
-   **Data type** -- the expected type of the extracted value. Supported types: **String**, **Number**, **Boolean**, **Datetime**. Cannot be changed once saved.
-   **Required** -- **Mandatory** or **Optional**. A Mandatory field with no matching value and no default raises an error at runtime; an Optional field is skipped or falls back to its default.
-   **JSON Path** -- the path into the sample input to extract the value from. The builder shows a dropdown of valid paths derived from your sample JSON, filtered by the selected data type. You pick a path from the list rather than typing it.
-   **Default value** -- optional fallback returned when the path is not found at runtime. Typed according to the selected data type.

## How to Use This Agent

Extract fields from an API response before sending an email:

```
trigger -> intelligent_actions("Look up customer order") -> json_extractor -> fixed_response("Order {{orderId}} for {{customerName}}") -> send_email
```

## Related Agents

-   [Extract Entities](/legacy-docs/agent-reference/core/extract-entities) -- for extracting structured data from unstructured text (uses an LLM).
-   [Convert to Text](/legacy-docs/agent-reference/core/convert-to-text) -- for converting JSON to a text representation.