--- title: "Transforming response structure in Connector builder | Supermetrics" slug: "transforming-response-structure" description: "Learn how to reshape JSON responses using data adapters to extract fields effectively, including flattening values and handling nested arrays." updated: 2026-06-04T07:42:25Z published: 2026-06-04T07:43:36Z canonical: "docs.supermetrics.com/transforming-response-structure" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # Transforming response structure Most APIs return JSON in a shape that maps directly to report fields. When an API returns data in a structure that doesn't, you can attach one or more **data adapters** to a report type's response to reshape the JSON in memory before fields are extracted from it. Common reasons to use such adapters include exploding nested arrays into separate rows, pulling a date key out of an object so it becomes a row value, or pivoting parallel arrays into per-row records. Data adapters are configured under `response.dataAdapters.items` on a report type's request. Each entry runs in the order it appears in the array, and each one sees the output of the previous transformation, not the raw API response. ## Configuration overview A data adapter has a `type` (which adapter to run) and a `config` (its parameters). Adapters are listed under `response.dataAdapters.items`: ``` "response": { "dataRows": { "source": "jsonPath", "value": "$.data.*" }, "dataAdapters": { "items": [ { "type": "[adapter type]", "config": { "dataPath": "[JSONPath]", ... } } ] } } ``` The `dataRows` JSONPath points at where the data rows are read from – but it is evaluated **after** all data adapters have run, so it must match the transformed structure, not the original response. > **Note:** Adapter `dataPath`, `valuesPath`, and similar properties always use JSONPath syntax (`$.foo.*`, `$.results.items`, etc.). ## Available adapters | Adapter | Use when | | --- | --- | | [Flatten values](https://docs.supermetrics.com/docs/flatten-values) | The response has nested arrays inside each item that should become separate rows. | | [Append key](https://docs.supermetrics.com/docs/append-key) | The response is an object keyed by a value (commonly a date) that should appear as a field on each row. | | [Time series](https://docs.supermetrics.com/docs/time-series) | The response contains parallel metric arrays (one value per day) that should become one row per date. | | [Match values by keys](https://docs.supermetrics.com/docs/match-values-by-keys) | The response has a `series` array and a `values` map keyed by series — and you need them pivoted into rows. | | [Combine keys with values](https://docs.supermetrics.com/docs/combine-keys-with-values) | The response splits column names and row values into separate arrays (header/row style). | | [Combine keys with nested values](https://docs.supermetrics.com/docs/combine-keys-with-nested-values) | Same idea as `combine_keys_with_values`, but the adapted data must be merged into an existing row instead of replacing it. | | [Extract fields by path](https://docs.supermetrics.com/docs/extract-fields-by-path) | A field defined once in a metadata section (such as a currency code in `headers`) needs to be copied onto each row. | | [Concat value to keys](https://docs.supermetrics.com/docs/concat-value-to-keys) | Field names need to be namespaced with another field's value (for example, prefixing `amount` with `charge_` or `refund_`). | | [Union nested arrays with key](https://docs.supermetrics.com/docs/union-nested-arrays-with-key) | The response has per-category arrays nested under a single object, and you want a single flat report tagged with the category name. | | [Aggregate values](https://docs.supermetrics.com/docs/aggregate-values) | The response has an array of per-segment objects, and you want a single row with totals rather than one row per segment. | | [Split to rows](https://docs.supermetrics.com/docs/split-to-rows) | A single field holds multiple comma-separated values that should become one row each. | ## Chaining multiple adapters A single response can be reshaped by several adapters at once — they run in the order they appear under `dataAdapters.items`, and each adapter sees the result of the previous one rather than the raw response. This means a `dataPath` that worked on the original JSON often needs to be different on the second or third adapter, because the structure has already changed. Below you can find a short example. Suppose an API returns a single object with a nested array of items, and each item carries its own nested array of daily breakdowns: ``` { "report": { "items": [ { "campaign": "Summer Sale", "daily": [ { "date": "2026-05-01", "clicks": 12 }, { "date": "2026-05-02", "clicks": 18 } ] } ] } } ``` The goal is to produce one row per day, carrying the campaign name. Two adapters get this done — the first extracts the items into the response root, the second explodes the daily breakdowns: ``` "dataAdapters": { "items": [ { "type": "flatten_values", "config": { "dataPath": "$", "valuesPath": "$.report.items.*" } }, { "type": "flatten_values", "config": { "dataPath": "$.*", "valuesPath": "$.daily.*" } } ] ```