> ## Documentation Index
> Fetch the complete documentation index at: https://learn.workflow.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert Table Rows

> Append, insert, or overwrite rows using Google Sheets column headers.

The **Insert Table Rows** action maps named values to a sheet's headers, then
appends them or writes them at a specific row. It is easier to maintain than a
raw range write when a table's columns have meaningful names.

## Inputs

| Input                     | Type                | Required | Description                                                   |
| ------------------------- | ------------------- | -------- | ------------------------------------------------------------- |
| **Third-party account**   | Google account      | Yes      | Account with write access.                                    |
| **Spreadsheet ID or URL** | String              | Yes      | Spreadsheet containing the table.                             |
| **Sheet Name**            | String              | Yes      | Sheet tab containing the table.                               |
| **Rows**                  | List of row objects | Yes      | Column/value pairs for each row.                              |
| **Header Row Number**     | Number              | No       | One-based header position. Defaults to `1`.                   |
| **Row Number**            | Number              | No       | One-based destination. Omit to append after existing data.    |
| **Overwrite**             | Boolean             | No       | With Row Number, replace cells instead of inserting new rows. |

For each row object, column names are matched to the closest header ignoring
capitalization, within a small spelling distance. Missing columns become empty
cells.

## Behavior by mode

<Tabs>
  <Tab title="Append">
    Leave **Row Number** empty. Sheets appends the rows after its detected table
    and returns the appended **Updated Range**.
  </Tab>

  <Tab title="Insert">
    Provide **Row Number** and leave **Overwrite** off. New sheet rows are
    inserted at that position, shifting existing rows down.
  </Tab>

  <Tab title="Overwrite">
    Provide **Row Number** and enable **Overwrite**. Values replace cells in the
    destination rows without shifting existing data.
  </Tab>
</Tabs>

## Outputs

| Output            | Type   | Description                     |
| ----------------- | ------ | ------------------------------- |
| **Updated Range** | String | A1 range written by the action. |

<Warning>
  In insert and overwrite modes, values are written as strings. Missing column
  values are written as empty strings across the table width.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No matching column was found">
    Confirm **Header Row Number** and the sheet name, then use column names
    close to the visible header text.
  </Accordion>
</AccordionGroup>