Google Sheets Integration

Automatically append every form submission as a new row in a Google Sheet — a simple way to keep a live, shareable spreadsheet of your entries alongside (or instead of) Contactum’s own Entries screen. Requires Contactum Pro with the Google Sheets module enabled.

---

Requirements #

• Contactum Pro, with the Google Sheets module active (Contactum → Modules)
• A Google Cloud project with a service account that has Sheets API access
• The service account’s JSON key file
• A target Google Sheet shared with that service account

---

1. Create a Google Service Account #

1. In Google Cloud Console, create a service account with access to the Google Sheets API, and download its JSON key.
2. Open the JSON key and note the client_email value inside it.
3. In Google Sheets, open the spreadsheet you want entries sent to, and share it with that client_email address as an Editor.
4. Copy the Spreadsheet ID from the sheet’s URL — it’s the long ID segment between /spreadsheets/d/ and /edit.

---

2. Connect Google Sheets in Contactum #

1. Go to Contactum → Settings → Integrations → Google Sheets.
2. Paste the full contents of your Service Account JSON Key.
3. Paste your Spreadsheet ID.
4. Click Verify Connection.

Contactum makes a live call to read the spreadsheet’s tab names to confirm both the credentials and the spreadsheet ID are correct. On success you’ll see confirmation and the status badge turns green.

To disconnect, click Disconnect Google Sheets — this clears the stored key and spreadsheet ID, and stops all row appending until reconnected.

---

3. Enable Google Sheets on a Specific Form #

1. Open the form in the builder.
2. Go to Form Settings → Integrations.
3. Toggle Google Sheets on, then click Configure.

---

4. Configure Sheet Settings #

Field	Description
Sheet	Which tab within your spreadsheet to append rows to. Click the refresh icon to load your spreadsheet’s tabs
Write field labels as the header row	Adds a header row with each field’s label the first time this sheet receives an entry

There’s no column-by-column field mapping. Unlike most integrations, Google Sheets automatically builds each row from every field on the form, in the form’s current field order, plus a trailing “Submitted At” timestamp column.

---

5. How It Works #

When a visitor submits the form:

1. Contactum checks the form has Google Sheets enabled and a Sheet is selected.
2. A row is built automatically from every field currently on the form, in field order, with a “Submitted At” timestamp appended as the last column. Checkbox-style fields with multiple selected values are joined into a single cell (comma-separated).
3. If Write field labels as the header row is enabled, Contactum checks whether a header row already exists; if the sheet appears empty at the top, it writes one. This only happens once ever per sheet — if you later clear or edit that header row yourself, Contactum won’t automatically rewrite it, since it only checks once.
4. The row is appended to the bottom of the selected sheet.

Important: because columns are built from the form’s current fields, adding, removing, or reordering fields on the form after you’ve started collecting rows will shift what lands in each column for new submissions, without any warning. If you plan to keep a long-running sheet, avoid restructuring the form’s fields later — or start a new sheet/tab when you do.

A failed row append does not block the form submission and is recorded in Contactum’s API Log for review.

---

Troubleshooting #

“Could not verify your spreadsheet connection” #

• Reconfirm the Spreadsheet ID was copied correctly from the sheet’s URL.
• Reconfirm the spreadsheet was shared with the service account’s client_email as an Editor.

Sheet dropdown is empty #

• Confirm the global connection shows verified and the Spreadsheet ID is correct.

Columns look misaligned after a form edit #

• This is expected — see the important note above. Google Sheets always writes based on the form’s current field order, not a fixed mapping.

The header row didn’t appear, or is now wrong #

• Contactum only ever attempts to write the header row once per sheet. If it was written incorrectly, or you cleared it afterward, you’ll need to update it manually in Google Sheets — Contactum won’t retry automatically.

---

Notes #

• Requires Contactum Pro with the Google Sheets module active — not available in the free plugin.
• Auth method: Google service account (JSON key), authenticated server-to-server.
• Credentials storage: stored in wp_options under the key contactum_google_sheets, with a small extra flag stored per sheet to track whether the header row has been attempted.
• A failed row append never blocks the form — the visitor’s experience is unaffected either way.