documenso/apps/docs/content/docs/developers/api/teams.mdx

---
title: Teams API
description: Manage team resources, documents, and templates with team-scoped API tokens.
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="warn">
  This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference,
  see the [OpenAPI Reference](https://openapi.documenso.com).
</Callout>

## Team Object

A team object contains the following properties:

| Property          | Type           | Description                                         |
| ----------------- | -------------- | --------------------------------------------------- |
| `id`              | number         | Unique team identifier                              |
| `name`            | string         | Team display name                                   |
| `url`             | string         | Unique team URL slug                                |
| `createdAt`       | string         | ISO 8601 timestamp                                  |
| `avatarImageId`   | string \| null | ID of the team's avatar image                       |
| `organisationId`  | string         | ID of the parent organisation                       |
| `currentTeamRole` | string         | Your role in the team: `ADMIN`, `MANAGER`, `MEMBER` |

### Example Team Object

```json
{
  "id": 123,
  "name": "Engineering",
  "url": "engineering",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "avatarImageId": null,
  "organisationId": "org_abc123",
  "currentTeamRole": "ADMIN"
}
```

## Team-Scoped API Tokens

API tokens in Documenso are always scoped to a specific team. When you create an API token, it is associated with the team you're currently working in.

### How Team Scoping Works

- Each API token belongs to exactly one team
- All API operations using that token automatically access that team's resources
- Documents, templates, and other resources created via the API belong to the token's team
- You cannot access resources from other teams with a single token

### Creating Team-Scoped Tokens

{/* prettier-ignore */}
<Steps>
  <Step>
    Navigate to your team's settings
  </Step>
  <Step>
    Go to **API Tokens**
  </Step>
  <Step>
    Click **Create Token**
  </Step>
  <Step>
    The token will be scoped to the current team
  </Step>
</Steps>

<Callout type="info">
  To work with multiple teams via API, create separate tokens for each team.
</Callout>

### Token Permissions

Your API token inherits permissions based on your role in the team:

| Role      | Permissions                                      |
| --------- | ------------------------------------------------ |
| `ADMIN`   | Full access to all team resources and settings   |
| `MANAGER` | Create, edit, and delete documents and templates |
| `MEMBER`  | Create and manage own documents                  |

## Working with Team Documents

When you use a team-scoped API token, all document operations are automatically scoped to that team.

### Create a Team Document

Documents created with a team token belong to that team:

<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "type": "DOCUMENT",
    "title": "Team Contract",
    "recipients": [
      {
        "email": "signer@example.com",
        "name": "John Smith",
        "role": "SIGNER"
      }
    ]
  }' \
  -F "files=@./contract.pdf;type=application/pdf"
```
</Tab>
<Tab value="TypeScript">
```typescript
const TEAM_API_TOKEN = process.env.DOCUMENSO_TEAM_API_TOKEN;

const form = new FormData();

const payload = {
  type: 'DOCUMENT',
  title: 'Team Contract',
  recipients: [
    {
      email: 'signer@example.com',
      name: 'John Smith',
      role: 'SIGNER',
    },
  ],
};

form.append('payload', JSON.stringify(payload));
form.append('files', fs.createReadStream('./contract.pdf'), {
  contentType: 'application/pdf',
});

const response = await fetch('https://app.documenso.com/api/v2/envelope/create', {
  method: 'POST',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
  body: form,
});

const { id } = await response.json();
console.log('Created team document:', id);
````
</Tab>
</Tabs>

### List Team Documents

Retrieve all documents belonging to the team:

<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
# List all team documents
curl -X GET "https://app.documenso.com/api/v2/envelope" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"

# Filter by status
curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"
````

</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/envelope', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
});

const { data, pagination } = await response.json();
console.log(`Found ${pagination.totalItems} team documents`);

````
</Tab>
</Tabs>

## Working with Team Templates

Templates created with a team token are shared across the team.

### Create a Team Template

<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/template/create" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "title": "NDA Template",
    "recipients": [
      {
        "email": "placeholder@example.com",
        "name": "Signer",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 0,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 10,
            "positionY": 80,
            "width": 30,
            "height": 5
          }
        ]
      }
    ]
  }' \
  -F "files=@./nda-template.pdf;type=application/pdf"
````

</Tab>
<Tab value="TypeScript">
```typescript
const form = new FormData();

const payload = {
  title: 'NDA Template',
  recipients: [
    {
      email: 'placeholder@example.com',
      name: 'Signer',
      role: 'SIGNER',
      fields: [
        {
          identifier: 0,
          type: 'SIGNATURE',
          page: 1,
          positionX: 10,
          positionY: 80,
          width: 30,
          height: 5,
        },
      ],
    },
  ],
};

form.append('payload', JSON.stringify(payload));
form.append('files', fs.createReadStream('./nda-template.pdf'), {
  contentType: 'application/pdf',
});

const response = await fetch('https://app.documenso.com/api/v2/template/create', {
  method: 'POST',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
  body: form,
});

const template = await response.json();
console.log('Created team template:', template.id);
````
</Tab>
</Tabs>

### List Team Templates

<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X GET "https://app.documenso.com/api/v2/template" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"
````

</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/template', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
});

const { data } = await response.json();
console.log('Team templates:', data);

````
</Tab>
</Tabs>

## Team Member Roles

| Role      | Description                                                         |
| --------- | ------------------------------------------------------------------- |
| `ADMIN`   | Full control over team settings, members, and all resources         |
| `MANAGER` | Can manage documents, templates, and view team resources            |
| `MEMBER`  | Can create and manage their own documents within the team           |

### Document Visibility

Team documents have visibility settings that control who can access them:

| Visibility         | Description                                      |
| ------------------ | ------------------------------------------------ |
| `EVERYONE`         | All team members can view the document           |
| `MANAGER_AND_ABOVE`| Only managers and admins can view                |
| `ADMIN`            | Only admins can view                             |

Set visibility when creating a document:

```typescript
const payload = {
  type: 'DOCUMENT',
  title: 'Confidential Agreement',
  visibility: 'ADMIN', // Only team admins can view
  recipients: [...],
};
````

## Multi-Team Workflow

To work with multiple teams, create and manage separate API tokens for each team.

### Example: Sync Documents Across Teams

```typescript
// Tokens for different teams
const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN;
const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN;

// Get pending documents from sales team
const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=PENDING', {
  headers: { Authorization: SALES_TEAM_TOKEN },
});
const salesDocs = await salesResponse.json();

// Get completed documents from legal team
const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=COMPLETED', {
  headers: { Authorization: LEGAL_TEAM_TOKEN },
});
const legalDocs = await legalResponse.json();

console.log(`Sales team: ${salesDocs.pagination.totalItems} pending`);
console.log(`Legal team: ${legalDocs.pagination.totalItems} completed`);
```

## Error Responses

| Status | Description                                       |
| ------ | ------------------------------------------------- |
| `401`  | Invalid or expired API token                      |
| `403`  | Token doesn't have permission for this operation  |
| `404`  | Resource not found or not accessible by this team |

### Example Error Response

```json
{
  "message": "You do not have permission to access this resource"
}
```

<Callout type="warn">
  API tokens can only access resources belonging to their associated team. Attempting to access
  resources from another team returns a 403 or 404 error.
</Callout>

## See Also

- [Documents API](/docs/developers/api/documents) - Create and manage documents
- [Templates API](/docs/developers/api/templates) - Work with document templates
- [Authentication](/docs/developers/getting-started/authentication) - Create and manage API tokens