ACTION_ID: google_sheet_add_data
NAME: Google Sheets: Add Data
CATEGORY: sheets
CREDITS: 0

Add data to a Google Sheet.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their Google account
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click Google Sheets and complete the OAuth flow

If the user has not connected Google Sheets, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Google Sheets connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

spreadsheets (spreadsheetsDropdown, required)
  Spreadsheets. Select the Spreadsheet to add data to. Values from
  google_spreadsheets.

select_sheet (inSheetDropdown, optional)
  Select sheet. Select the sheet to add data to. Values from
  google_spreadsheet_sheets.

value_input_option (dropdown, optional)
  Value Input Option. Type of data interpretation. Values:
    - { id: "USER_ENTERED", name: "User Entered" }
    - { id: "RAW", name: "Raw" } (default)

add_data_to_columns (jsonArrayCreateNew, required)
  Add Data To Columns. Select Columns from the object and add Values
  or Create a New Column.

================================================================================
2. OUTPUTS
================================================================================

(no response fields — this action writes to the sheet and returns nothing.)

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve the dropdowns via Get Action Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/spreadsheets
       (body: {})
       → user's spreadsheets. `value` is the spreadsheet ID.

  POST .../options/select_sheet
       (body: { "context": { "spreadsheets": "<spreadsheet_id>" } })
       → tabs (sheets) inside the chosen spreadsheet. `value` is the
         sheet name.

Configure Action body:

{
  "inputs": {
    "spreadsheets": "<spreadsheet_id>",
    "select_sheet": "Sheet1",
    "value_input_option": "USER_ENTERED",
    "add_data_to_columns": [
      { "name": "First Name",  "value": "{{input.first_name}}" },
      { "name": "Email",       "value": "{{input.email}}" },
      { "name": "Company",     "value": "{{input.company_name}}" }
    ]
  }
}

Field-by-field:
  - spreadsheets         Google spreadsheet ID from the
                         `spreadsheets` options call.
  - select_sheet         Tab/sheet name from the `select_sheet`
                         options call. Optional; defaults to the
                         first sheet.
  - value_input_option   `RAW` (default — values inserted as-is) or
                         `USER_ENTERED` (Google Sheets parses values
                         like a user typing them, so `=A1+B1` becomes
                         a formula).
  - add_data_to_columns  `[{name, value}]` — `name` is the column
                         header on the destination sheet (created if
                         missing); `value` is what to write per row.

================================================================================
4. KEY NOTES
================================================================================

- Append-only — every run adds a new row at the bottom of the sheet.
  Use `google_sheet_upsert_row` if you need create-or-update by a
  key column.
- Column `name`s that don't exist on the sheet are created as new
  columns at the right edge.
- `value_input_option: "RAW"` is the safe default. Use `"USER_ENTERED"`
  only if you want Google Sheets to interpret formulas, dates, etc.
  from your written values.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: enrichment -> google_sheet_add_data (append output to a
sheet).

================================================================================
6. WHEN TO USE
================================================================================

Use google_sheet_add_data for append-only writes to a Google
Sheet.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need upsert by a key column
  -> google_sheet_upsert_row
     (https://floqer.com/docs/action-detail/google_sheet_upsert_row.txt)

Need to read existing rows
  -> google_sheets_lookup_rows
     (https://floqer.com/docs/action-detail/google_sheets_lookup_rows.txt)

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt