# POST /spreadsheets/templates

**Resource:** [Spreadsheets](./spreadsheets.md)  
**Scopes:** `spreadsheets:write`  
**Write operation:** yes

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.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `name` | body | string | yes | Template name |
| `description` | body | string | no | Optional description |
| `columns` | body | array | no | Column definitions. Each: { header: string, data_type: "text"\|"long_text"\|"number"\|"date"\|"boolean"\|"dropdown"\|"user_ref"\|"opportunity_ref", description?: string, options?: Array<string \| { value: string, color?: "slate"\|"red"\|"orange"\|"amber"\|"yellow"\|"green"\|"teal"\|"blue"\|"indigo"\|"purple"\|"pink" }>, width?: number, archived?: true }. dropdown requires options with >= 2 non-empty entries. |
| `default_sort` | body | array | no | Optional default ordering. Each entry: { column: "<header>", direction: "asc"\|"desc" }. Rows display in this order and imports are sorted the same way. Pass null to clear. |
| `merge_rules` | body | object | no | Optional merge-on-insert config. Shape: { group_by: string[], period_start: string, period_end: string, tolerance_days?: number, concat_columns?: { [header]: { separator: string, order_by: string, direction?: "asc"\|"desc" } } }. Pass null to clear. |

## Request example

```bash
{
  "name": "Project Checklist",
  "columns": [
    {
      "header": "Task",
      "data_type": "text"
    },
    {
      "header": "Notes",
      "data_type": "long_text"
    },
    {
      "header": "Assigned To",
      "data_type": "user_ref"
    },
    {
      "header": "Linked Opportunity",
      "data_type": "opportunity_ref"
    },
    {
      "header": "Due Date",
      "data_type": "date"
    },
    {
      "header": "Complete",
      "data_type": "boolean"
    },
    {
      "header": "Status",
      "data_type": "dropdown",
      "options": [
        {
          "value": "Open",
          "color": "green"
        },
        {
          "value": "In Progress",
          "color": "amber"
        },
        {
          "value": "Done",
          "color": "slate"
        }
      ]
    }
  ],
  "default_sort": [
    {
      "column": "Status",
      "direction": "asc"
    }
  ]
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`