JSON Response Parser — Deep Dive

The JSON Parser is the most complex and powerful part of the API Builder. It transforms raw JSON responses from an API into named, structured fields that your workflow nodes can use.

Why Response Mapping Matters

When an API returns data, it comes as raw JSON — a nested tree of objects and arrays. Your workflow doesn't know what's inside unless you tell it. Response mapping is the bridge:

Without mapping, the workflow would receive the entire JSON blob as a single opaque value. With mapping, each piece of data gets a clean label that downstream nodes can reference by name.

The 3-Step Process

Step 1: Paste a Sample Response

Paste a real JSON response from the API into the text area. You can get this from:

• The API's documentation (most docs include example responses)
• A test request using Postman, cURL, or the browser
• The API's interactive Swagger/OpenAPI explorer

{
  "data": {
    "temp": 72,
    "city": "London",
    "conditions": {
      "wind": 5,
      "humidity": 80
    }
  }
}

Click "Analyze JSON" to parse the response structure.

Step 2: Select Fields to Use

After analysis, a tree view shows every path discovered in the JSON:

• Leaf fields (actual values like strings, numbers, booleans) — shown with a blue path and an "Add" button
• Group fields (objects or arrays that contain other fields) — shown in purple with an "Add All Subfields" button

Click "Add" on individual fields to include them, or "Add All Subfields" on a group to bulk-add every leaf field underneath it.

How the parser discovers fields: The parser walks through the JSON tree and records every path from root to leaf. For nested objects, it uses dot notation: data.conditions.wind. For arrays, it samples the first element to discover the structure.

Array Handling — Why [0] Becomes [*]

When the parser finds an array, it inspects the first element ([0]) to learn the structure. But when the integration runs for real, you want data from all elements, not just the first. So the parser automatically converts specific indices ([0]) to wildcards ([*]), telling the system "apply this path to every item in the array."

For example:

This means "extract the name field from every product in the array."

Step 3: Refine Configuration

After selecting fields, fine-tune the mapping:

When to Use a Root Accessor

Many APIs wrap their actual data inside a container:

{
  "status": "ok",
  "data": {
    "temperature": 72,
    "city": "London"
  }
}

If you only care about the contents of data, set Root Accessor to data. Your output field paths then start from inside data (e.g., temperature instead of data.temperature).

Smart Naming

When you add fields, the parser auto-generates descriptive labels:

How collisions are handled:

1. If a field name is generic (Value, Unit, Id, Name, Key, Type, Code), the parser automatically prepends the parent name for context
2. If two fields would get the same label, the parser prepends the parent name to the second one
3. If collisions still exist, a numeric suffix is added (Temperature, Temperature2)

You can always edit labels manually — the auto-generated names are just a starting point.

Manual Field Definition

If the JSON parser doesn't cover your needs, you can add output fields manually:

1. Click "Add Manually" in the output fields section
2. Enter a Node Output Label (any descriptive name)
3. Enter a Source JSON Path (the dot-notation path to the value)

This is useful when:

• You can't paste a sample response (API docs don't provide one)
• You need a field from a deeply nested path the parser didn't reach
• You want to rename fields for clarity

No Fields Defined

If you don't define any output fields, the entire raw JSON response is returned as a single output. This works for simple APIs, but structured outputs are almost always better for workflow reliability.

Next Steps

• Examples — See the JSON parser in action with real-world APIs
• Troubleshooting & Glossary — Common JSON parsing issues and term reference