> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams

> Organize users into teams with role-based access to templates and submissions.

## Overview

Teams let you organize account members into groups with shared access to specific templates. Each team has members with assigned roles and a set of template access grants. Users can belong to multiple teams.

## Team Object

The compact team representation returned in list endpoints:

```json theme={null}
{
  "id": 7,
  "name": "Legal Department",
  "description": "Handles all contract and NDA templates",
  "member_count": 5,
  "created_at": "2026-03-15T09:00:00Z"
}
```

The full team representation includes members and template access grants:

```json theme={null}
{
  "id": 7,
  "name": "Legal Department",
  "description": "Handles all contract and NDA templates",
  "member_count": 5,
  "created_at": "2026-03-15T09:00:00Z",
  "members": [
    {
      "id": 101,
      "email": "sarah@yourcompany.com",
      "first_name": "Sarah",
      "last_name": "Chen",
      "role": "admin",
      "added_at": "2026-03-15T09:00:00Z"
    },
    {
      "id": 102,
      "email": "james@yourcompany.com",
      "first_name": "James",
      "last_name": "Wilson",
      "role": "member",
      "added_at": "2026-03-15T09:05:00Z"
    },
    {
      "id": 103,
      "email": "maria@yourcompany.com",
      "first_name": "Maria",
      "last_name": "Garcia",
      "role": "member",
      "added_at": "2026-03-16T10:00:00Z"
    },
    {
      "id": 104,
      "email": "david@yourcompany.com",
      "first_name": "David",
      "last_name": "Park",
      "role": "member",
      "added_at": "2026-03-17T14:30:00Z"
    },
    {
      "id": 105,
      "email": "lisa@yourcompany.com",
      "first_name": "Lisa",
      "last_name": "Thompson",
      "role": "member",
      "added_at": "2026-03-18T08:15:00Z"
    }
  ],
  "template_accesses": [
    {
      "template_id": 201,
      "template_name": "Standard NDA",
      "access_level": "full",
      "granted_at": "2026-03-15T09:10:00Z"
    },
    {
      "template_id": 202,
      "template_name": "Employment Contract",
      "access_level": "full",
      "granted_at": "2026-03-15T09:10:00Z"
    },
    {
      "template_id": 205,
      "template_name": "Vendor Agreement",
      "access_level": "read_only",
      "granted_at": "2026-03-20T11:00:00Z"
    }
  ]
}
```

### Member Roles

| Role     | Permissions                                                                 |
| -------- | --------------------------------------------------------------------------- |
| `admin`  | Add/remove members, manage template access, edit team settings, delete team |
| `member` | View team templates, create submissions from team templates                 |

## List Teams

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://spitshake.io/api/teams" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": 7,
      "name": "Legal Department",
      "description": "Handles all contract and NDA templates",
      "member_count": 5,
      "created_at": "2026-03-15T09:00:00Z"
    },
    {
      "id": 8,
      "name": "Sales Team",
      "description": "Proposals and order forms",
      "member_count": 12,
      "created_at": "2026-03-20T14:00:00Z"
    },
    {
      "id": 9,
      "name": "Human Resources",
      "description": "Onboarding and benefits documents",
      "member_count": 3,
      "created_at": "2026-04-01T08:00:00Z"
    }
  ]
  ```
</ResponseExample>

## Get Team

Retrieve the full team object including members and template accesses.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://spitshake.io/api/teams/7" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 7,
    "name": "Legal Department",
    "description": "Handles all contract and NDA templates",
    "member_count": 5,
    "created_at": "2026-03-15T09:00:00Z",
    "members": [
      {
        "id": 101,
        "email": "sarah@yourcompany.com",
        "first_name": "Sarah",
        "last_name": "Chen",
        "role": "admin",
        "added_at": "2026-03-15T09:00:00Z"
      },
      {
        "id": 102,
        "email": "james@yourcompany.com",
        "first_name": "James",
        "last_name": "Wilson",
        "role": "member",
        "added_at": "2026-03-15T09:05:00Z"
      },
      {
        "id": 103,
        "email": "maria@yourcompany.com",
        "first_name": "Maria",
        "last_name": "Garcia",
        "role": "member",
        "added_at": "2026-03-16T10:00:00Z"
      },
      {
        "id": 104,
        "email": "david@yourcompany.com",
        "first_name": "David",
        "last_name": "Park",
        "role": "member",
        "added_at": "2026-03-17T14:30:00Z"
      },
      {
        "id": 105,
        "email": "lisa@yourcompany.com",
        "first_name": "Lisa",
        "last_name": "Thompson",
        "role": "member",
        "added_at": "2026-03-18T08:15:00Z"
      }
    ],
    "template_accesses": [
      {
        "template_id": 201,
        "template_name": "Standard NDA",
        "access_level": "full",
        "granted_at": "2026-03-15T09:10:00Z"
      },
      {
        "template_id": 202,
        "template_name": "Employment Contract",
        "access_level": "full",
        "granted_at": "2026-03-15T09:10:00Z"
      },
      {
        "template_id": 205,
        "template_name": "Vendor Agreement",
        "access_level": "read_only",
        "granted_at": "2026-03-20T11:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

## Create Team

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/teams" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Finance Team",
      "description": "Invoice and payment document management"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 10,
    "name": "Finance Team",
    "description": "Invoice and payment document management",
    "member_count": 1,
    "created_at": "2026-04-08T15:00:00Z",
    "members": [
      {
        "id": 101,
        "email": "sarah@yourcompany.com",
        "first_name": "Sarah",
        "last_name": "Chen",
        "role": "admin",
        "added_at": "2026-04-08T15:00:00Z"
      }
    ],
    "template_accesses": []
  }
  ```

  ```json 422 — Validation Error theme={null}
  {
    "error": "Team name is required and must be between 1 and 100 characters."
  }
  ```
</ResponseExample>

## Update Team

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://spitshake.io/api/teams/10" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Finance & Accounting",
      "description": "Invoice, payment, and audit document management"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 10,
    "name": "Finance & Accounting",
    "description": "Invoice, payment, and audit document management",
    "member_count": 1,
    "created_at": "2026-04-08T15:00:00Z"
  }
  ```
</ResponseExample>

## Delete Team

Deleting a team removes all member associations and template access grants. It does not delete the members or templates themselves.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://spitshake.io/api/teams/10" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Team 'Finance & Accounting' has been deleted."
  }
  ```
</ResponseExample>

## Add Member

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/teams/7/members" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": 106,
      "role": "member"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 106,
    "email": "alex@yourcompany.com",
    "first_name": "Alex",
    "last_name": "Rivera",
    "role": "member",
    "added_at": "2026-04-08T15:30:00Z"
  }
  ```

  ```json 422 — Already a Member theme={null}
  {
    "error": "User alex@yourcompany.com is already a member of this team."
  }
  ```
</ResponseExample>

## Update Member Role

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://spitshake.io/api/teams/7/members/102" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "role": "admin"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 102,
    "email": "james@yourcompany.com",
    "first_name": "James",
    "last_name": "Wilson",
    "role": "admin",
    "added_at": "2026-03-15T09:05:00Z"
  }
  ```
</ResponseExample>

## Remove Member

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://spitshake.io/api/teams/7/members/105" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "User lisa@yourcompany.com has been removed from the team."
  }
  ```

  ```json 422 — Last Admin theme={null}
  {
    "error": "Cannot remove the last admin from a team. Promote another member to admin first."
  }
  ```
</ResponseExample>

## Grant Template Access

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/teams/7/template_accesses" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "template_id": 210,
      "access_level": "full"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "template_id": 210,
    "template_name": "Consulting Agreement",
    "access_level": "full",
    "granted_at": "2026-04-08T15:45:00Z"
  }
  ```
</ResponseExample>

### Access Levels

| Level       | Create Submissions | View Submissions | Edit Template |
| ----------- | ------------------ | ---------------- | ------------- |
| `full`      | Yes                | Yes              | Yes           |
| `read_only` | No                 | Yes              | No            |

## Revoke Template Access

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://spitshake.io/api/teams/7/template_accesses/205" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Template access for 'Vendor Agreement' has been revoked from this team."
  }
  ```
</ResponseExample>