ACTION_ID: google_sheet_upsert_row
NAME: Google Sheets: Upsert Data
CATEGORY: Integrations
CREDITS: 0

Upsert data to a Google Sheet.

PREREQUISITE: Google account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

1. INPUTS

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

select_sheet (inSheetDropdown, optional)
  Select sheet. Values from google_spreadsheet_sheets.

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

select_lookup_column (inPrimaryColumnDropdown, required)
  Select Lookup Column. Select column for lookup. Values from
  google_sheet_primary_column.

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: {})
  POST .../options/select_sheet
       (body: { "context": { "spreadsheets": "<spreadsheet_id>" } })
  POST .../options/select_lookup_column
       (body: { "context": { "spreadsheets": "<spreadsheet_id>",
                             "select_sheet": "Sheet1" } })
       → column headers eligible as the lookup key.

Configure Action body:

{
  "inputs": {
    "spreadsheets": "<spreadsheet_id>",
    "select_sheet": "Leads",
    "value_input_option": "USER_ENTERED",
    "select_lookup_column": "Email",
    "add_data_to_columns": [
      { "name": "Email",       "value": "{{input.email}}" },
      { "name": "First Name",  "value": "{{input.first_name}}" },
      { "name": "Status",      "value": "Enriched" }
    ]
  }
}

Field-by-field:
  - spreadsheets          Google spreadsheet ID.
  - select_sheet          Tab name on the spreadsheet.
  - value_input_option    `RAW` (default — values inserted as-is) or
                          `USER_ENTERED` (Sheets parses formulas, dates).
  - select_lookup_column  Column header used as the upsert match key.
                          Must be one of the headers on the chosen
                          sheet — fetch via Get Action Field Options.
  - add_data_to_columns   `[{name, value}]` — values to write on
                          create OR update. Include the lookup column
                          here too so it's set on freshly-created rows.

4. KEY NOTES

- Match logic: rows whose `select_lookup_column` cell equals the
  corresponding `value` in `add_data_to_columns` are updated; if no
  match, a new row is appended.
- The lookup column must be present in `add_data_to_columns` — that's
  how the action knows what value to match against.
- Column `name`s in `add_data_to_columns` that don't exist on the
  sheet are created as new columns at the right edge.

5. WHERE IT FITS IN A WORKFLOW

Pattern: enrichment -> google_sheet_upsert_row (keyed on a column)
-> idempotent Sheet sync.

6. WHEN TO USE

Use google_sheet_upsert_row for idempotent writes keyed by a column.

7. WHEN NOT TO USE

Need append-only
  -> action-detail/google_sheet_add_data.txt

Need to read existing rows
  -> action-detail/google_sheets_lookup_rows.txt

Last updated: 2026-04-28.