# Spreadsheets

Manage spreadsheet templates (column definitions) and populated spreadsheets (row data). Spreadsheets can be linked to opportunities and are also created automatically when a form with a spreadsheet field is submitted. Scopes: spreadsheets:read, spreadsheets:write, spreadsheets:delete.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /spreadsheets/templates

List all spreadsheet templates for this workspace.

**Scopes:** `spreadsheets:read` — [full detail](./spreadsheets/get-spreadsheets-templates.md)

### GET /spreadsheets/templates/:id

Get a spreadsheet template with full column definitions. Use this to resolve column IDs to headers before writing row data.

**Scopes:** `spreadsheets:read` — [full detail](./spreadsheets/get-spreadsheets-templates-id.md)

### POST /spreadsheets/templates

Create a new spreadsheet template with column definitions. Each column needs header + data_type. Valid data_type values: text, long_text, number, date, boolean, dropdown, user_ref, opportunity_ref. dropdown requires options[] with at least 2 entries (plain strings or {value, color?} objects for coloured chips). default_sort sets the row display order. If columns are omitted, two default columns (Item and Notes) are created.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/post-spreadsheets-templates.md)

### PATCH /spreadsheets/templates/:id

Update a spreadsheet template. columns is a FULL REPLACEMENT -- include all existing columns with their current id to preserve them. To remove a column without losing row data, set archived: true. Changing columns does not modify existing row data. Same data_type values and option shapes as POST.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/patch-spreadsheets-templates-id.md)

### DELETE /spreadsheets/templates/:id

Delete a spreadsheet template and cascade-delete all spreadsheets derived from it.

**Scopes:** `spreadsheets:delete` — [full detail](./spreadsheets/delete-spreadsheets-templates-id.md)

### GET /spreadsheets

List all populated spreadsheets. Filter by template or opportunity.

**Scopes:** `spreadsheets:read` — [full detail](./spreadsheets/get-spreadsheets.md)

### GET /spreadsheets/:id

Get a populated spreadsheet with metadata, parent template column definitions (parent_columns), and all rows ordered by row_index. Each row cells object is keyed by column ID.

**Scopes:** `spreadsheets:read` — [full detail](./spreadsheets/get-spreadsheets-id.md)

### POST /spreadsheets

Create a new populated spreadsheet from a template. Starts with no rows. Optionally link to an opportunity.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/post-spreadsheets.md)

### PATCH /spreadsheets/:id

Update a spreadsheet name, linked opportunity, or archived status.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/patch-spreadsheets-id.md)

### DELETE /spreadsheets/:id

Delete a populated spreadsheet and all its rows. Does not affect the parent template.

**Scopes:** `spreadsheets:delete` — [full detail](./spreadsheets/delete-spreadsheets-id.md)

### GET /spreadsheets/:id/rows

List all rows in a spreadsheet ordered by row_index. Each row has a cells object keyed by column ID.

**Scopes:** `spreadsheets:read` — [full detail](./spreadsheets/get-spreadsheets-id-rows.md)

### POST /spreadsheets/:id/rows

Append a new row to a spreadsheet. Provide cells as an object keyed by column ID (not header name). Retrieve column IDs from GET /spreadsheets/:id (parent_columns) or GET /spreadsheets/templates/:id.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/post-spreadsheets-id-rows.md)

### PATCH /spreadsheets/:id/rows/:rowId

Update the cells or row_index of an existing row. cells replaces the entire cells object -- include all column values you want to retain.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/patch-spreadsheets-id-rows-rowId.md)

### DELETE /spreadsheets/:id/rows/:rowId

Delete a single row from a spreadsheet.

**Scopes:** `spreadsheets:delete` — [full detail](./spreadsheets/delete-spreadsheets-id-rows-rowId.md)

### POST /spreadsheets/:id/rows/bulk

Append up to 100 rows in a single request. Rows are inserted in input order. Returns created[] with original input index on each entry, and errors[] for any rows that failed. Use this instead of looping POST /spreadsheets/:id/rows for imports larger than ~10 rows.

**Scopes:** `spreadsheets:write` — [full detail](./spreadsheets/post-spreadsheets-id-rows-bulk.md)