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

Upsert 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 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
  -> google_sheet_add_data
     (https://floqer.com/docs/action-detail/google_sheet_add_data.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