Docs · Getting started

From installation to a live table in about four minutes.

Steps one to three need no account at all. Activation only matters when you want to fetch from a URL. Nothing here assumes you write code.

On this page 1 · Install the add-on 2 · Open the sidebar 3 · Paste JSON, insert a table 4 · Activate for URL imports 5 · Your first API request 6 · Save a credential 7 · Keep it fresh Choosing an array mode When something breaks

Step 01

Install JSON for Sheets

Install JSON for Sheets from the Google Workspace Marketplace and accept the Google permission prompt. Interactive actions can read and write only the spreadsheet currently open. If you enable a schedule, Google Picker asks you to authorize that specific spreadsheet so it can refresh while closed. The add-on does not search Drive or access Gmail, contacts, calendars, or non-Sheets Drive content.

Install from Marketplace

Step 02

Open the sidebar

In any spreadsheet, go to the Extensions menu and choose JSON for Sheets, then Open JSON for Sheets. The same menu includes the import and export tools plus your account and usage screen.

Extensions → JSON for Sheets → Open JSON for Sheets

Step 03

Paste JSON and insert a table

Choose Paste, drop a payload in, and the explorer appears. Tick the fields you want, pick a destination, and read the predicted row and column count. Press Insert table. This whole flow runs inside the spreadsheet — no sign-in, no request counted, and your data never reaches us.

If your payload wraps the array in an envelope, click the array in the tree instead of hunting for the path — the root path fills itself in.

Untick anything you do not need. Fewer columns means a table people will actually read.

Writing to a new sheet is the safe default while you are learning the shape of a payload.

Step 04

Activate, for URL imports only

Fetching from a URL goes through our service so quotas and URL safety checks can be applied; responses are always fetched fresh and are not cached. Only when you choose a remote feature, JSON for Sheets uses the Google account already authorized for the add-on and activates the current spreadsheet installation. There is no separate sign-in and no card is required.

No account needed

All 12 local functions · paste JSON · read JSON from a cell · the explorer · range to JSON

Needs a free account

Public and authenticated API requests · account-scoped usage · fresh, uncached responses

Your credential is encrypted in Supabase Vault, is never returned to Apps Script after saving, and is scoped to your account, this product, and its original request origin.

Step 05

Your first API request

Choose Paste JSON, Selected cell, From file, Public URL, API request, or Paste cURL. Local .json files up to 5 MB are read inside the add-on and never uploaded to JSON for Sheets servers. For a remote endpoint, configure the request in the sidebar, press Preview JSON, choose your root path and fields, then write the table to the selected cell or a new sheet.

Remote imports intentionally run through the sidebar or a saved schedule under the active user's installation. The remote JSON_IMPORT formula is disabled so spreadsheet recalculation cannot silently spend another user's allowance.

Public URL → Preview JSON → Choose fields → Write table

Never put a token in a formula argument — it would be visible to anyone with the spreadsheet. Authenticated requests belong in the sidebar, where the secret stays server-side.

Step 06

Save a credential once

Open Connections, choose a type, paste the secret, name it something you will recognise in six months, and save it. Requests then reference the connection by name. The value is encrypted on save and never shown again. Delete and recreate the connection to rotate it.

Bearer token API key in header API key in query Basic auth Custom secret headers

Step 07

Keep it fresh

Preview the request whenever you want fresh data, then choose the output mode that matches what the sheet is for. Save a remote import to run it on demand or schedule it on a paid plan:

Overwrite

Replace the managed range with the latest response. Right for a current-state snapshot.

Append

Add new rows below the existing ones. Right for an event log you want to accumulate.

Update or append

Match on one unique key, update those rows, append the rest. Your own extra columns are preserved and nothing is deleted. The key must exist in both the response and the destination header, and duplicates are refused.

A scheduled request rechecks your plan before every run, so a downgrade disables an hourly schedule rather than failing quietly for weeks.

Choosing an array mode

The single decision that determines whether your table is useful. Ask what one row should mean.

rows

One row per child item. Choose it when you want to pivot or sum by the child — line items, tags, participants. Watch the multiplier: 500 orders with 4 items each is 2,000 rows.

join

One row per record, the array collapsed into one cell. Choose it when the array is labels you want to read, not numbers you want to total.

json

One row per record, the array kept as JSON. Choose it when you want to decide later — JSON_VALUE() can reach inside afterwards.

When something breaks

Read the exact error shown in the sidebar or spreadsheet cell before changing the request. If you contact support, include that error text, the approximate time, the source type, and the steps that produced it. Remove secrets and sensitive payload data first.

401 Unauthorized

The saved token was rejected. Rotate the connection rather than editing the request.

Response too large

Narrow the path, select fewer fields, or reduce the API's page size. Your per-response limit is on the pricing page.

Blocked destination

The URL resolved to a private or internal address. Local and intranet endpoints cannot be reached — this is deliberate and not configurable.

Duplicate key in source

Upsert refuses to guess which row wins. Pick a genuinely unique field, or deduplicate upstream.

Still stuck? Email support with the exact error text →